@activatus/code-standards 0.0.0-stage → 2.0.0

package/docs/Standards/stylelint.md

@@ -0,0 +1,178 @@
+---
+sidebar_position: 5
+sidebar_label: "Stylelint"
+---
+
+# Stylelint Configuration
+
+Components are styled with [Tailwind CSS](/Standards/styling), and Stylelint lints the CSS that is still written by hand — `globals.css` and any CSS Modules. Start from the config below that matches the project:
+
+| Config | Use when |
+| --- | --- |
+| [Plain CSS](#plain-css-and-css-modules) | Plain CSS and CSS Modules (`.module.css`) |
+| [SCSS](#scss) | SCSS / Sass |
+
+## Installation
+
+```bash
+pnpm add -D stylelint stylelint-config-standard stylelint-config-recess-order
+```
+
+For SCSS projects, install `stylelint-config-standard-scss` in place of `stylelint-config-standard`:
+
+```bash
+pnpm add -D stylelint stylelint-config-standard-scss stylelint-config-recess-order
+```
+
+## Usage
+
+Create `stylelint.config.mjs` in your project root:
+
+### Plain CSS and CSS Modules
+
+```js title="stylelint.config.mjs"
+/** @type {import("stylelint").Config} */
+export default {
+  ignoreFiles: ["**/vendor/**"],
+  extends: ["stylelint-config-standard", "stylelint-config-recess-order"],
+  rules: {
+    "selector-max-id": 0,
+    "property-no-vendor-prefix": true,
+    "color-function-notation": "modern",
+    "import-notation": "string",
+    "at-rule-no-unknown": [
+      true,
+      { ignoreAtRules: ["theme", "utility", "variant", "custom-variant", "source", "plugin"] },
+    ],
+  },
+  overrides: [
+    {
+      files: ["**/*.module.css"],
+      rules: {
+        "color-named": "never",
+        "color-no-hex": true,
+        "selector-class-pattern": [
+          "^[a-z][a-zA-Z0-9]*$",
+          { message: "Expected class selector to be camelCase" },
+        ],
+      },
+    },
+  ],
+};
+```
+
+### SCSS
+
+```js title="stylelint.config.mjs"
+/** @type {import("stylelint").Config} */
+export default {
+  ignoreFiles: ["**/vendor/**"],
+  extends: ["stylelint-config-standard-scss", "stylelint-config-recess-order"],
+  rules: {
+    "selector-max-id": 0,
+    "property-no-vendor-prefix": true,
+    "color-function-notation": "modern",
+  },
+};
+```
+
+### Project-specific overrides
+
+Add to the `rules` block:
+
+```js
+export default {
+  // ...
+  rules: {
+    // ...
+    // project-specific overrides
+    "selector-max-type": 3,
+  },
+};
+```
+
+Add a lint script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:css": "stylelint \"**/*.{css,scss}\"",
+    "lint:css:fix": "stylelint \"**/*.{css,scss}\" --fix"
+  }
+}
+```
+
+## Extended configs
+
+| Config | Used by | Purpose |
+| --- | --- | --- |
+| `stylelint-config-standard` | Plain CSS and CSS Modules | Stylelint's recommended modern CSS rules |
+| `stylelint-config-standard-scss` | SCSS | Standard rules + SCSS-specific rules |
+| `stylelint-config-recess-order` | all | Enforces Bootstrap/RECESS property order |
+
+## Property order
+
+Properties are sorted using the [RECESS order](https://github.com/stordahl/stylelint-config-recess-order) (the same order used by Bootstrap). The broad grouping:
+
+1. Positioning (`position`, `top`, `z-index`, …)
+2. Box model (`display`, `width`, `margin`, `padding`, …)
+3. Typography (`font`, `line-height`, `color`, …)
+4. Visual (`background`, `border`, `opacity`, …)
+5. Misc (`transition`, `animation`, …)
+
+## Key rule decisions
+
+### `selector-max-id: 0`
+
+ID selectors create specificity that is nearly impossible to override without escalating to `!important`. Use classes instead.
+
+### `property-no-vendor-prefix: true`
+
+Vendor prefixes should be added by **Autoprefixer** in the build pipeline, not written by hand. Hand-written prefixes become stale as browser support improves. Configure Autoprefixer with a Browserslist query instead.
+
+### `color-function-notation: "modern"`
+
+Enforces `rgb(255 0 0 / 50%)` instead of `rgba(255, 0, 0, 0.5)`. The modern syntax is part of CSS Color Level 4 and is supported in all modern browsers.
+
+### `ignoreFiles`: third-party code is exempt
+
+CSS in a `vendor/` folder is not ours, so it is not linted. See [Third-party code is exempt](/Standards/eslint#third-party-code-is-exempt).
+
+### Tailwind: `import-notation: "string"` and `at-rule-no-unknown`
+
+`stylelint-config-standard` rejects `@import "tailwindcss"` and does not know Tailwind's at-rules. These two settings allow the import and the `@theme`, `@utility`, `@variant`, `@custom-variant`, `@source` and `@plugin` at-rules.
+
+### Custom properties: kebab-case
+
+`stylelint-config-standard` requires CSS variables to be kebab-case (`--color-brand-primary`). See [CSS Styling](/Standards/styling#css-variables).
+
+### CSS Modules: `color-named: never` and `color-no-hex`
+
+Colours come from the [global colour variables](/Standards/styling#-colours-always-come-from-global-variables). A CSS Module may not contain `white` or `#3b82f6` — it references `var(--color-white)` or `var(--color-brand-primary)`. Colour values are only written in `globals.css`.
+
+### CSS Modules: `selector-class-pattern: camelCase`
+
+CSS Modules are consumed in JavaScript as `styles.myClass`. Kebab-case names require bracket notation (`styles["my-class"]`), which is easy to mistype. camelCase names allow dot notation and are consistent with JavaScript naming conventions.
+
+### SCSS: `scss/load-no-partial-leading-underscore`
+
+Leading underscores on `@import` paths are a Sass 1.x convention for marking partials. With `@use` and `@forward` (the modern Sass module system), the underscore is handled automatically — including it manually in `@use` paths is an error. `stylelint-config-standard-scss` enforces this.
+
+## Editor integration
+
+### VS Code
+
+Install the [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) extension, then add to workspace settings:
+
+```json
+{
+  "stylelint.validate": ["css", "scss"],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.stylelint": "explicit"
+  }
+}
+```
+
+### JetBrains IDEs
+
+Go to **Settings → Languages & Frameworks → Style Sheets → Stylelint** and enable it.

package/docs/Standards/styling.md

@@ -0,0 +1,284 @@
+---
+sidebar_position: 10
+---
+
+# CSS Styling
+
+Standards for styling React components and applications.
+
+---
+
+## 🎨 Tailwind CSS
+
+Use Tailwind CSS utility classes for all component styling. Tailwind is compatible with React Server Components and is the foundation [shadcn/ui](/Guides/component-library-workflow) is built on.
+
+```tsx
+// Button.tsx
+export const Button = () => {
+  return (
+    <button className="rounded-md bg-brand-primary px-8 py-4 text-white transition-colors hover:bg-brand-primary-hover">
+      Click me
+    </button>
+  );
+};
+```
+
+---
+
+## 📐 Layout: Flexbox First
+
+**Build every layout with flexbox.** Reach for `flex` first, and split the layout into child components so each one styles only itself.
+
+**Only use CSS grid when it is specifically asked for.**
+
+### ✅ Flex parent, child components
+
+The parent arranges its children with flex. Each child is its own component with its own styles:
+
+```tsx title="pageHeader/PageHeader.tsx"
+import { PageHeaderActions } from "./pageHeaderActions";
+import { PageHeaderTitle } from "./pageHeaderTitle";
+
+export const PageHeader = () => {
+  return (
+    <header className="flex items-center justify-between gap-4">
+      <PageHeaderTitle />
+      <PageHeaderActions />
+    </header>
+  );
+};
+```
+
+```tsx title="pageHeader/pageHeaderActions/PageHeaderActions.tsx"
+export const PageHeaderActions = () => {
+  return (
+    <div className="flex items-center gap-2">
+      <button className="rounded-md bg-brand-primary px-4 py-2 text-white">
+        Save
+      </button>
+      <button className="rounded-md px-4 py-2 text-text">Cancel</button>
+    </div>
+  );
+};
+```
+
+### ❌ One component styling everything
+
+```tsx
+// ❌ Bad — grid without being asked, and every piece styled in one place
+export const PageHeader = () => {
+  return (
+    <header className="grid grid-cols-[1fr_auto] items-center gap-4">
+      <div className="flex flex-col gap-1">
+        <h1 className="text-2xl font-semibold text-text">Invoices</h1>
+        <p className="text-sm text-text">All invoices for this account</p>
+      </div>
+      <div className="flex items-center gap-2">
+        <button className="rounded-md bg-brand-primary px-4 py-2 text-white">
+          Save
+        </button>
+        <button className="rounded-md px-4 py-2 text-text">Cancel</button>
+      </div>
+    </header>
+  );
+};
+```
+
+### Rules
+
+- **Flex first.** `flex`, `flex-col`, `gap-*`, `items-*` and `justify-*` cover almost every layout.
+- **The parent positions, the child styles itself.** A parent sets direction, spacing and alignment. Each child component owns its own padding, colour and typography.
+- **Split into child components** rather than growing one long `className` or a deep tree of `div`s. Each child gets [its own folder](/Structure/component-organization#nested-components).
+- **Space with `gap`**, not margins on the children.
+- **Grid only when asked.** Do not choose CSS grid on your own — use it only when the task specifically asks for a grid.
+
+---
+
+## ❌ Avoid These
+
+- ❌ **CSS grid**, unless it was specifically asked for
+
+- ❌ **Hard-coded colours** — hex, `rgb()` or named colours anywhere outside the theme
+- ❌ **Arbitrary colour values** (`bg-[#3b82f6]`) — if the colour is not in the palette, it is not used
+- ❌ **Inline styles** (except for dynamic values)
+- ❌ **Styled-components or emotion** (not compatible with RSC)
+- ❌ **Global CSS files for component styles**
+
+---
+
+## ✅ Colours Always Come From Global Variables
+
+**Strictly follow the global colour palette.** Every colour is defined **once**, as a global colour variable in the theme. Components never contain a colour value — they reference a variable.
+
+The palette is two things, and nothing else:
+
+- **Tailwind's built-in colours** (`bg-white`, `text-slate-900`, `border-blue-500`) — allowed
+- **Project colours** added to the `@theme` block (`bg-brand-primary`)
+
+A colour that is in neither is not used. If a design calls for a new colour, add it to the global palette first — never write a one-off value in a component.
+
+### ✅ Define the colours
+
+Each project defines its colours once, in its global stylesheet:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+
+@theme {
+  --color-brand-primary: #3b82f6;
+  --color-brand-primary-hover: #2563eb;
+  --color-brand-secondary: #64748b;
+  --color-surface: #fff;
+  --color-text: #0f172a;
+}
+
+[data-theme="dark"] {
+  --color-brand-primary: #60a5fa;
+  --color-brand-primary-hover: #93c5fd;
+  --color-surface: #0f172a;
+  --color-text: #f8fafc;
+}
+```
+
+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.
+
+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](/Standards/documentation).
+
+### ✅ Use the colours
+
+```tsx
+// ✅ Good — colours come from the theme
+<p className="bg-surface text-text">Hello</p>
+<button className="bg-brand-primary text-white">Save</button>
+
+// ❌ Bad — colours hard-coded in the component
+<p className="bg-[#fff] text-[#0f172a]">Hello</p>
+<button style={{ background: "#3b82f6", color: "white" }}>Save</button>
+```
+
+When you do write CSS by hand, reference the variable — never the value:
+
+```css
+/* ✅ Good */
+.chart {
+  color: var(--color-white);
+  background: var(--color-brand-primary);
+}
+
+/* ❌ Bad */
+.chart {
+  color: white;
+  background: #3b82f6;
+}
+```
+
+Tailwind's built-in colours are variables too — `white` is `var(--color-white)`.
+
+---
+
+## 💡 Best Practices
+
+### Tailwind utilities
+
+- **Use for**: All component styling
+- **Layout**: Flexbox first; grid only when specifically asked
+- **Colours**: Global palette only — Tailwind colours and project colours from `@theme` — never arbitrary values
+- **Long class lists**: Extract a component, not a CSS class
+- **Conditional classes**: Use `clsx`
+- **Class order**: Sorted automatically by [Prettier](/Standards/prettier#tailwind-class-sorting) — do not sort by hand
+
+### Global CSS
+
+- **Use for**: The Tailwind import, the `@theme` block, theme overrides, global resets
+- **Location**: `app/globals.css`
+- **Avoid**: Component-specific styles
+- **Import only**: In the root layout
+
+### CSS Modules
+
+- **Use for**: The rare style Tailwind cannot express (complex keyframe animations, third-party overrides)
+- **File naming**: `componentName.module.css`
+- **Colours**: `var(--color-*)` only — Stylelint rejects hex and named colours in CSS Modules
+- **Import**: Co-located with component
+
+### Inline Styles
+
+- **Use for**: Dynamic values only (e.g., `style={{ height: sliderValue }}`)
+- **Avoid**: Static styles that should be Tailwind utilities
+
+---
+
+## 📁 File Organization
+
+### Component Styles
+
+Styles live in the component's `className` — there is no separate style file:
+
+```text
+components/
+└── button/
+    ├── Button.tsx
+    ├── Button.test.tsx
+    └── index.ts
+```
+
+### Global Styles
+
+```text
+app/
+├── globals.css              # Tailwind import, @theme colour variables, resets
+├── layout.tsx
+└── page.tsx
+```
+
+---
+
+## 🎯 Naming Conventions
+
+### CSS Variables
+
+**Use kebab-case for variable names.** This is the CSS convention, it is what Tailwind's theme namespaces (`--color-*`, `--spacing-*`, `--font-*`) require, and Stylelint enforces it.
+
+```css
+/* ✅ Good */
+--color-brand-primary: #3b82f6;
+--spacing-unit: 0.25rem;
+--radius-card: 0.5rem;
+
+/* ❌ Bad */
+--colorBrandPrimary: #3b82f6;
+--spacing_unit: 0.25rem;
+--RadiusCard: 0.5rem;
+```
+
+Name colours by **role**, not by value: `--color-brand-primary`, not `--color-blue`.
+
+### CSS Modules
+
+**Use camelCase for class names**, because they are read in JavaScript as `styles.primaryButton`:
+
+```css
+/* ✅ Good */
+.button {
+}
+.primaryButton {
+}
+.submitButton {
+}
+
+/* ❌ Bad */
+.primary-button {
+}
+.submit_button {
+}
+```
+
+---
+
+## 📚 Related Documentation
+
+- [Stylelint](/Standards/stylelint) - Linting for hand-written CSS
+- [Component Organization](/Structure/component-organization) - How to organize component files
+- [Folder Structure](/Structure/folder-structure) - Overall project structure
+- [Naming Conventions](/Structure/naming-conventions) - File and folder naming rules

package/docs/Standards/tech-stack.md

@@ -0,0 +1,156 @@
+---
+sidebar_position: 11
+---
+
+# Tech Stack
+
+Standard technology choices for Activatus projects.
+
+---
+
+## 📋 Standard Stack
+
+- **Framework**: Next.js 16 (App Router)
+- **Language**: TypeScript 7
+- **Package Manager**: pnpm (monorepo: workspaces)
+- **Styling**: Tailwind CSS
+- **Node Version**: `^22.11 || ^24 || >=26`
+- **Build Tool**: Turbopack (Next.js built-in)
+
+### TypeScript 7
+
+TypeScript 7 is the compiler rewritten in Go. It is a drop-in replacement for
+the JavaScript implementation for compiling and type-checking, but two things
+change for tooling:
+
+- **There is no `tsserver`.** The compiler is its own language server, started
+  with `tsc --lsp --stdio`. Editors and tools that drove TypeScript through
+  `typescript-language-server` have nothing to drive; they talk to `tsc`
+  directly instead.
+- **It answers diagnostics on request.** TypeScript 7 supports LSP pull
+  diagnostics, so a client that only waits for a `publishDiagnostics` push can
+  sit there believing a file is clean.
+
+### Parameterise a library's generics
+
+A generic whose default is a permissive index signature returns `any` at every use, and
+the code reads as though it were typed. Storyblok's story type is the one to watch:
+
+```ts
+// storyblok-js-client
+interface ISbStoryData<Content = ISbComponentType<string> & { [index: string]: any }> {
+  content: Content;
+  // …
+}
+```
+
+Left bare, `ISbStoryData` makes `story.content` that `any`-indexed fallback. Every field
+access resolves, nothing is checked, and a renamed block field fails in the browser
+rather than in CI. Declare the block and pass it:
+
+```ts
+export interface HeroBlokType extends ISbComponentType<"hero"> {
+  headline: string;
+  subhead?: string;
+  callToAction?: CallToActionBlokType[];
+}
+
+// story.content.headline is string; story.content.headlien is a compile error.
+const story: ISbStoryData<HeroBlokType> = await getStory();
+```
+
+The parameter flows, so the surrounding types carry it too — `ISbResult`'s
+`data.stories` becomes `ISbStoryData<HeroBlokType>[]`. Where a story can hold one of several
+blocks, make `Content` a discriminated union on `component` and switch on it.
+
+Extend the published type rather than restating its fields: `ISbComponentType<"hero">`
+already contributes `_uid`, `component` and `_editable`, and a hand-written copy drifts
+the moment the library changes.
+
+Read every library generic this way. An unparameterised one with a permissive default is
+usually a silent `any`, not a sensible fallback. The [`/typescript` skill](/Standards/agent-skills)
+applies this as a rule.
+
+---
+
+## 🧪 Testing Stack
+
+- **Unit Testing**: Vitest
+- **Component Testing**: @testing-library/react
+- **E2E Testing**: Playwright
+- **Coverage**: @vitest/coverage-v8
+
+---
+
+## 🗄️ Database & Backend
+
+- **Database**: Supabase (PostgreSQL)
+- **ORM**: Supabase client (direct)
+- **Validation**: Zod schemas
+
+---
+
+## ⚛️ State Management
+
+- **Server State**: @tanstack/react-query
+- **Global State**: Zustand
+- **Form State**: @tanstack/react-form
+
+---
+
+## 📦 Package Versions
+
+See `package.json` for specific version requirements. Key dependencies:
+
+```json
+{
+  "dependencies": {
+    "next": "^16.3.5",
+    "react": "^19.3.0",
+    "@tanstack/react-query": "^5.85.5",
+    "zustand": "^5.0.7"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8",
+    "@testing-library/react": "^16.1.0",
+    "playwright": "^1.63.0"
+  }
+}
+```
+
+---
+
+## 🎨 UI Libraries
+
+- **Design System**: Custom (Radix UI primitives)
+- **Icons**: Lucide React
+- **Forms**: React Hook Form
+- **Tables**: TanStack Table
+
+---
+
+## 🔧 Development Tools
+
+- **Linting**: ESLint 9+
+- **Formatting**: Prettier
+- **Git Hooks**: Husky
+- **Monorepo**: Turborepo
+- **Documentation**: Docusaurus
+
+---
+
+## Version Requirements
+
+### Node.js
+
+- **Consumer minimum**: 20.0.0, matching the packages' `engines` requirement
+- **Repository version**: 24, pinned in `.nvmrc`
+- **Package manager minimum for consumers**: pnpm 9, matching the root `engines` requirement
+- **Repository package manager**: pnpm 11.23.0, pinned in `package.json#packageManager`
+
+### TypeScript
+
+- **Version**: 5.0+
+- **Strict Mode**: Enabled
+- **Target**: ES2022+

package/docs/Structure/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Structure",
+  "position": 7
+}