@starci/eslint-canon-fe 4.0.0 → 6.0.0

package/docs/lists.md

@@ -0,0 +1,74 @@
+# Lists
+
+Law module: `lists.mjs`. Catalogue: R65 FE_SIZE_AND_STATE_BUDGET, sub-check `FE_LIST_KEY`.
+
+A list is items with identity. React reconciles a rendered list by `key`; a missing, positional or random key hands a deleted row's state to its neighbour or remounts every row. A component prop written as an object or array literal inside `.map` is a new value per row per render, so a memoised row never hits.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/list-item-has-key`
+
+Every element a `.map` callback returns carries a `key`.
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+rows.map((row) => <Row row={row} />)
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+rows.map((row) => <Row key={row.id} row={row} />)
+```
+
+**Finding code:** `FE_LIST_KEY`
+
+**Vì sao (why):** Phần tử trả từ `.map` ở `<file>` không có `key`, nên React nhận diện hàng theo vị trí và hàng bị đổi state khi xoá hoặc sắp xếp lại.
+
+**Cách sửa:** Thêm `key` lấy từ id của dữ liệu; với fragment dùng `<Fragment key={...}>`.
+
+## `starci-fe/no-index-key`
+
+A list key is stable data identity, never the map index or a random value. A static array written in place, or a callback that ignores its item (`(_, index) =>`), is exempt.
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+rows.map((row, index) => <Row key={index} row={row} />)
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+rows.map((row) => <Row key={row.id} row={row} />)
+```
+
+**Finding code:** `FE_LIST_KEY`
+
+**Vì sao (why):** `key` ở `<file>` lấy từ chỉ số của `.map` hoặc giá trị sinh ngẫu nhiên; chỉ số là vị trí, không phải danh tính.
+
+**Cách sửa:** Dùng id mà dữ liệu mang (`key={row.id}`); không dùng index, `Math.random`, `Date.now`.
+
+## `starci-fe/no-inline-literal-prop-in-list`
+
+No object or array literal as a prop of a component rendered inside `.map`.
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+rows.map((row) => <Avatar key={row.id} props={{ size: "sm" }} />)
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+const AVATAR_PROPS = { size: "sm" } as const
+rows.map((row) => <Avatar key={row.id} props={AVATAR_PROPS} />)
+```
+
+**Finding code:** `FE_LIST_KEY`
+
+**Vì sao (why):** Component trong `.map` ở `<file>` nhận object hoặc array literal làm prop: mỗi hàng mỗi lần render một giá trị mới, memo không bao giờ trúng.
+
+**Cách sửa:** Nâng hằng số ra ngoài component hoặc dựng một lần trước `.map`.

package/docs/native-controls.md

@@ -0,0 +1,73 @@
+# No native form controls
+
+Law module: `native-controls.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL.
+
+`<select>`, `<input>`, `<textarea>` and `<button>` are rendered by the grammar in product source, at every tier. If the grammar lacks the control, add it to the grammar.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-native-form-control`
+
+Use the grammar's renderers; never a bare select, input, textarea or button.
+
+**Invalid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+<button onClick={go} />
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+<Button onPress={go}>{t("go")}</Button>
+```
+
+**Finding code:** `FE_NATIVE_FORM_CONTROL`
+
+**Vì sao (why):** `<tag>` thô ở `<file>`. Dùng renderer của grammar.
+
+**Cách sửa:** Thay bằng thành phần của grammar; nếu chưa có, thêm vào grammar thay vì vẽ tại chỗ.
+
+## `starci-fe/no-native-img`
+
+Use `next/image`, never a bare `<img>` (catalogue R62, sub-check `FE_NATIVE_IMAGE`).
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<img src={src} alt={t("cover")} />
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<Image src={src} alt={t("cover")} width={40} height={40} />
+```
+
+**Finding code:** `FE_NATIVE_IMAGE`
+
+**Vì sao (why):** `<img>` thô ở `<file>`: tải ảnh gốc, không giữ chỗ nên trang nhảy khi ảnh tải xong.
+
+**Cách sửa:** Dùng `Image` của `next/image` với `width` và `height` (hoặc `fill` và `sizes`) và `alt` từ catalog.
+
+## `starci-fe/image-has-size`
+
+`next/image` carries `width` and `height`, or `fill` with `sizes` (sub-check `FE_NATIVE_IMAGE`).
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<Image src={src} alt={t("cover")} />
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<Image src={src} alt={t("cover")} width={40} height={40} />
+```
+
+**Finding code:** `FE_NATIVE_IMAGE`
+
+**Vì sao (why):** `Image` ở `<file>` thiếu `width` và `height` (hoặc `fill` mà thiếu `sizes`): trình duyệt không giữ chỗ được.
+
+**Cách sửa:** Cho đủ `width` và `height`, hoặc `fill` trong khung có kích thước kèm `sizes`.

package/docs/next-conventions.md

@@ -0,0 +1,232 @@
+# Next conventions and the one locale pattern
+
+Law module: `next-conventions.mjs`. Catalogue: FE_NEXT_CONVENTIONS, R58 (html lang), R59 (i18n placement, single-file half).
+
+One locale pattern everywhere: `next-intl`, a `[locale]` segment, default `vi`, `localePrefix: "as-needed"`, and `proxy.ts` (Next 16) instead of `middleware.ts`.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-middleware-file`
+
+`middleware.ts` is forbidden: the request interceptor is `proxy.ts` and exports `proxy`.
+
+**Invalid** (`src/middleware.ts`)
+
+```ts
+export function middleware() {}
+```
+
+**Valid** (`src/proxy.ts`)
+
+```ts
+export function proxy(request) { return request }
+```
+
+**Finding code:** `FE_NEXT_CONVENTIONS`
+
+**Vì sao (why):** `<file>` dùng tên `middleware`. Từ Next 16 bộ chặn request là `proxy.ts` và xuất `proxy`.
+
+**Cách sửa:** Đổi tên tệp thành `proxy.ts` và đổi export thành `proxy`.
+
+## `starci-fe/locale-segment-is-locale`
+
+The locale route segment is `[locale]`, never `[lang]`.
+
+**Invalid** (`src/app/[lang]/page.tsx`)
+
+```ts
+export default function Page() {}
+```
+
+**Valid** (`src/app/[locale]/page.tsx`)
+
+```ts
+export default function Page() {}
+```
+
+**Finding code:** `FE_I18N_PLACEMENT`
+
+**Vì sao (why):** Tệp `<file>` nằm dưới segment ngôn ngữ không phải `[locale]`. Chỉ có một mẫu: `next-intl`, `[locale]`, mặc định `vi`.
+
+**Cách sửa:** Đổi tên thư mục segment thành `[locale]`.
+
+## `starci-fe/no-second-i18n-stack`
+
+`next-intl` is the only i18n library.
+
+**Invalid** (`any file`)
+
+```ts
+import { useTranslation } from "react-i18next"
+```
+
+**Valid** (`any file`)
+
+```ts
+import { useTranslations } from "next-intl"
+```
+
+**Finding code:** `FE_I18N_PLACEMENT`
+
+**Vì sao (why):** `<file>` nhập một thư viện i18n thứ hai. App chỉ dùng `next-intl` qua `modules/i18n`.
+
+**Cách sửa:** Chuyển sang `next-intl`; xóa thư viện còn lại.
+
+## `starci-fe/html-lang-from-locale`
+
+`<html lang>` is taken from the `[locale]` segment, never a literal.
+
+**Invalid** (`src/app/[locale]/layout.tsx`)
+
+```ts
+<html lang="en">
+```
+
+**Valid** (`src/app/[locale]/layout.tsx`)
+
+```ts
+<html lang={locale}>
+```
+
+**Finding code:** `FE_I18N_LITERAL`
+
+**Vì sao (why):** `<html lang>` ở `<file>` là chữ cứng. Thuộc tính `lang` phải lấy từ segment `[locale]`.
+
+**Cách sửa:** Dùng `lang={locale}` từ tham số của layout `[locale]`.
+
+## `starci-fe/page-exports-metadata`
+
+Every `page.tsx` exports `metadata` or `generateMetadata` (catalogue R54, sub-check `FE_PAGE_METADATA_MISSING`).
+
+**Invalid** (`src/app/[locale]/courses/page.tsx`)
+
+```tsx
+export default function Page() { return <CoursesPage /> }
+```
+
+**Valid** (`src/app/[locale]/courses/page.tsx`)
+
+```tsx
+export async function generateMetadata() { return { title: t("courses.title") } }
+export default function Page() { return <CoursesPage /> }
+```
+
+**Finding code:** `FE_PAGE_METADATA_MISSING`
+
+**Vì sao (why):** `<file>` là `page.tsx` nhưng không export `metadata` hoặc `generateMetadata`; mọi trang trong nhánh mang cùng một tiêu đề.
+
+**Cách sửa:** Export `metadata` (hoặc `generateMetadata` khi tiêu đề lấy từ dữ liệu) với tiêu đề và mô tả lấy từ catalog thông điệp.
+
+## `starci-fe/no-null-suspense-fallback`
+
+`<Suspense>` has a fallback that renders something; `fallback={null}` is forbidden (catalogue R53, sub-check `FE_SUSPENSE_NULL_FALLBACK`).
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<Suspense fallback={null}><Feed /></Suspense>
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<Suspense fallback={<FeedSkeleton />}><Feed /></Suspense>
+```
+
+**Finding code:** `FE_SUSPENSE_NULL_FALLBACK`
+
+**Vì sao (why):** `<Suspense>` ở `<file>` có `fallback` rỗng: người dùng thấy khoảng trống thay vì trạng thái đang tải.
+
+**Cách sửa:** Truyền skeleton (trạng thái loading) của đúng thứ đang tải làm `fallback`.
+
+## `starci-fe/navigation-from-intl`
+
+`Link`, `useRouter`, `usePathname` and `redirect` come from `modules/i18n/navigation`, not from Next (catalogue R59, sub-check `FE_I18N_NAVIGATION`).
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+import { useRouter } from "next/navigation"
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+import { useRouter } from "@/modules/i18n/navigation"
+```
+
+**Finding code:** `FE_I18N_NAVIGATION`
+
+**Vì sao (why):** `<file>` nhập `Link`, `useRouter`, `usePathname` hoặc `redirect` từ Next, không biết locale: đường dẫn mất tiền tố `[locale]`.
+
+**Cách sửa:** Nhập từ `modules/i18n/navigation`, được next-intl dựng từ `routing.ts`.
+
+## `starci-fe/no-native-anchor`
+
+An internal link is `Link` from `modules/i18n/navigation`; an external `_blank` link carries `rel` (catalogue R59, sub-check `FE_I18N_NAVIGATION`).
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<a href="/courses">{t("courses")}</a>
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+<Link href={routes.courses()}>{t("courses")}</Link>
+```
+
+**Finding code:** `FE_I18N_NAVIGATION`
+
+**Vì sao (why):** `<a>` ở `<file>` trỏ route nội bộ (tải lại cả trang, mất locale, mất prefetch) hoặc mở tab mới mà không có `rel`.
+
+**Cách sửa:** Dùng `Link` từ `modules/i18n/navigation` với href dựng bởi `modules/routes`; liên kết `_blank` thêm `rel="noopener noreferrer"`.
+
+## `starci-fe/no-hardcoded-route`
+
+A route path is built by `modules/routes`, never written as a literal at a link or a navigation call (catalogue R57, sub-check `FE_ROUTE_HARDCODED`).
+
+**Invalid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+router.push("/agentos/workspaces/new")
+```
+
+**Valid** (`src/components/blocks/Feed/component.tsx`)
+
+```tsx
+router.push(routes.newWorkspace())
+```
+
+**Finding code:** `FE_ROUTE_HARDCODED`
+
+**Vì sao (why):** `<file>` viết thẳng đường dẫn route ở nơi gọi; route đổi chỗ thì bản sao trỏ vào 404.
+
+**Cách sửa:** Dựng href bằng hàm của `modules/routes` và dùng đúng hàm đó ở mọi nơi.
+
+## `starci-fe/i18n-stack-in-one-module`
+
+next-intl's routing, navigation, request config and middleware factories are called only in the i18n package (or the only app's `modules/i18n`).
+
+`defineRouting` (`next-intl/routing`), `createNavigation` (`next-intl/navigation`), `getRequestConfig` (`next-intl/server`) and `createMiddleware` (`next-intl/middleware`), resolved by the import that binds the called name (a renamed import or a namespace member counts), are called only in a file of slot `fe.package.i18n` (`packages/<family>-i18n`, exporting `createAppI18n`), or in a `fe.modules.i18n` file of a repository that declares exactly one app. In a multi-app repository each app's `modules/i18n` calls the package factory. It sits beside `no-second-i18n-stack`, which refuses another i18n library at its import; this rule refuses a second copy of next-intl's own stack.
+
+**Invalid** (`apps/web/src/modules/i18n/request.ts`, a repository with two apps)
+
+```ts
+import { getRequestConfig } from "next-intl/server"
+export default getRequestConfig(async () => ({ locale: "vi", messages: {} }))
+```
+
+**Valid** (`apps/web/src/modules/i18n/index.ts`)
+
+```ts
+import { createAppI18n } from "@nivo/i18n"
+export const i18n = createAppI18n({ locales: ["vi"] })
+```
+
+**Finding code:** `FE_I18N_PLACEMENT`
+
+**Vì sao (why):** `<file>` tự dựng một tầng của stack next-intl (`defineRouting`, `createNavigation`, `getRequestConfig`, `createMiddleware`). Stack chỉ được viết một lần cho cả repo.
+
+**Cách sửa:** Gọi factory `createAppI18n` của gói i18n dùng chung trong `modules/i18n/index.ts` và nhập kết quả; repo một app thì chỉ viết stack trong `modules/i18n` của app đó.

package/docs/size-and-state-budget.md

@@ -0,0 +1,73 @@
+# Size and state budget
+
+Law module: `size-and-state-budget.mjs`. Catalogue: R65 FE_SIZE_AND_STATE_BUDGET.
+
+A component file is at most 300 lines; a connected unit holds at most 6 `useState` and reads at most 6 data hooks; there is no hand-written polling loop. `HFS_SIZE_GROWTH` (no growth against the parent commit) is the architecture machine's; these are the absolute file-local limits.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/component-line-budget`
+
+A component file has at most 300 lines.
+
+**Invalid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+// a 301-line component file
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+// 300 lines or fewer
+```
+
+**Finding code:** `FE_SIZE_AND_STATE_BUDGET`
+
+**Vì sao (why):** `<file>` dài `<n>` dòng, vượt ngưỡng 300 dòng của một component.
+
+**Cách sửa:** Tách phần vẽ khỏi phần dữ liệu và tách từng khu vực thành đơn vị riêng.
+
+## `starci-fe/unit-hook-budget`
+
+A unit has at most 6 state hooks and 6 data hooks.
+
+**Invalid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+const Feed = () => { /* 7 x useState */ }
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+const Feed = () => { /* up to 6 x useState and 6 data hooks */ }
+```
+
+**Finding code:** `FE_SIZE_AND_STATE_BUDGET`
+
+**Vì sao (why):** `<unit>` có `<n>` hook dữ liệu / `<m>` useState, vượt ngưỡng 6.
+
+**Cách sửa:** Gom trạng thái đổi cùng nhau vào reducer hoặc hook riêng; tách mỗi vùng dữ liệu thành block kết nối riêng.
+
+## `starci-fe/no-hand-rolled-polling`
+
+No `setInterval` and no self-scheduling `setTimeout`: one refresh mechanism per resource.
+
+**Invalid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+useEffect(() => { const t = setInterval(load, 5000) }, [])
+```
+
+**Valid** (`src/components/blocks/Feed/index.tsx`)
+
+```ts
+const d = useQueryFeedSwr({ refreshInterval: 5000 })
+```
+
+**Finding code:** `FE_SIZE_AND_STATE_BUDGET`
+
+**Vì sao (why):** `<unit>` tự viết vòng poll (`setInterval` hoặc `setTimeout` tự gọi lại).
+
+**Cách sửa:** Làm tươi qua hook dữ liệu (`refreshInterval`) hoặc socket, mỗi resource đúng một cơ chế.

package/docs/size-growth.md

@@ -0,0 +1,29 @@
+# Size growth
+
+Law module: `size-growth.mjs`. Catalogue: R20 HFS_SIZE_GROWTH.
+
+A source file has a line budget, `ruleParams.fe.fileLines` of `knowledge/hfs/slots.yaml`, read through the slot view `hfsOf(context).ruleParams` (the package ships its own copy of the manifest in `runtime/`). A file over the budget may not be new and may not be longer than it was at the parent commit; a file within the budget is never a finding. The rule takes no option, there is no baseline file and no allowlist: the record is the repository's own history. `*.d.ts` declaration files are not governed.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/file-size-growth`
+
+A source file over the budget is neither new nor longer than its recorded size.
+
+**Invalid** (`src/components/Card/index.tsx`)
+
+```ts
+// a new file with more lines than the budget, or an existing file over the budget that gained a line
+```
+
+**Valid** (`src/components/Card/index.tsx`)
+
+```ts
+// a file within the budget, or an oversized file that stayed the same size or shrank
+```
+
+**Finding code:** `HFS_SIZE_GROWTH`
+
+**Vì sao (why):** `<file>` vượt ngân sách dòng: file mới đã dài quá mức, hoặc file cũ dài hơn bản ở commit cha. Mỗi file phải nhỏ để một người đọc hết và một bài test phủ hết.
+
+**Cách sửa:** Tách phần mới sang file riêng theo trách nhiệm; một file đã vượt ngân sách chỉ được giữ nguyên hoặc ngắn lại.

package/docs/spec-quality.md

@@ -0,0 +1,147 @@
+# Spec quality
+
+Law module: `spec-quality.mjs`. Catalogue: R67 FE_SPEC_QUALITY, R60 (real catalogue in specs).
+
+A spec is a claim about one unit's behaviour: no class-string pinning, it imports the unit beside it, no spec for a barrel, no `as unknown as`, an axe assertion for every connected screen, and a real `next-intl` catalogue instead of a mock.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-class-string-in-spec`
+
+A component spec asserts behaviour, never a class string.
+
+**Invalid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+expect(el).toHaveClass("bg-primary")
+```
+
+**Valid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+expect(screen.getByRole("button", { name: "Save" })).toBeEnabled()
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` ghim chuỗi class. Spec kiểm hành vi, không kiểm stylesheet.
+
+**Cách sửa:** Assert theo role, tên, trạng thái hoặc chữ hiển thị.
+
+## `starci-fe/spec-tests-its-neighbour`
+
+A spec imports its sibling subject: `X.test.tsx` imports `./X`.
+
+**Invalid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+import { Row } from "../Row"
+```
+
+**Valid** (`src/components/leaves/Chip/Chip.test.tsx`)
+
+```ts
+import { Chip } from "./Chip"
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` không import chủ thể nằm cạnh nó.
+
+**Cách sửa:** Đưa spec về cạnh chủ thể, hoặc test đúng đơn vị nằm cạnh.
+
+## `starci-fe/no-barrel-spec`
+
+No `index.spec.ts(x)` beside an `index.ts(x)` that holds only imports and re-exports. The sibling is read and parsed: an `index.ts` that declares a function, class or value (implementation) may have its spec; a missing sibling is no finding.
+
+**Invalid** (`src/hooks/index.spec.ts`, beside `src/hooks/index.ts` = `export * from "./useFeed"`)
+
+```ts
+// file: src/hooks/index.spec.ts
+```
+
+**Valid** (`src/modules/browser-storage/index.spec.ts`, beside an `index.ts` that declares `createStore` and exports two stores)
+
+```ts
+// file: src/modules/browser-storage/index.spec.ts
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` đặt cạnh một barrel. Barrel không có hành vi để test.
+
+**Cách sửa:** Xóa spec; test từng đơn vị mà barrel xuất lại, cạnh chính đơn vị đó.
+
+## `starci-fe/no-double-cast-in-spec`
+
+A spec builds its values with the type's own shape, not `as unknown as`.
+
+**Invalid** (`any spec`)
+
+```ts
+const x = { id: 1 } as unknown as Course
+```
+
+**Valid** (`any spec`)
+
+```ts
+const x = mock<Course>()
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` ép kiểu hai lần (`as unknown as`).
+
+**Cách sửa:** Dựng giá trị bằng factory có kiểu (`mock<T>()` hoặc fixture builder).
+
+## `starci-fe/connected-spec-has-axe`
+
+The spec of a connected block or feature runs an axe assertion.
+
+**Invalid** (`src/components/blocks/Feed/index.test.tsx`)
+
+```ts
+it("renders", () => {})
+```
+
+**Valid** (`src/components/blocks/Feed/index.test.tsx`)
+
+```ts
+it("a11y", async () => { expect(await axe(container)).toHaveNoViolations() })
+```
+
+**Finding code:** `FE_SPEC_QUALITY`
+
+**Vì sao (why):** Spec `<file>` của màn hình kết nối không có assert axe.
+
+**Cách sửa:** Thêm `expect(await axe(container)).toHaveNoViolations()`.
+
+## `starci-fe/no-mocked-translations`
+
+A spec renders with the real catalogue; it never mocks `next-intl`. A `vi.mock("next-intl/server", factory)` in the spec of a server helper (no provider exists for it) is allowed when the factory - or a `vi.hoisted` block it reads - uses the app's real catalogue (an import that resolves into `modules/i18n/messages/`); a literal or key-echoing server mock, an automock, and any mock of the client `next-intl` stay findings.
+
+**Invalid** (`any spec`)
+
+```ts
+vi.mock("next-intl", () => ({}))
+```
+
+**Valid** (`any spec`)
+
+```ts
+render(<NextIntlClientProvider messages={messages} locale="vi" />)
+```
+
+```ts
+import messages from "@/modules/i18n/messages/vi.json"
+vi.mock("next-intl/server", async () => {
+  const { createTranslator } = await import("next-intl")
+  return { getTranslations: async () => createTranslator({ locale: "vi", messages }) }
+})
+```
+
+**Finding code:** `FE_I18N_CATALOG`
+
+**Vì sao (why):** Spec `<file>` giả lập `next-intl`, nên chỉ kiểm khóa chứ không kiểm catalog thật.
+
+**Cách sửa:** Component client: render trong `NextIntlClientProvider` với `messages/<locale>.json` thật. Helper server (`next-intl/server`): factory của mock dựng translator từ catalog thật (`createTranslator` với `modules/i18n/messages/<locale>.json`).

package/docs/status-colors.md

@@ -0,0 +1,32 @@
+# Status colours: text and icons take the soft pair
+
+Law module: `status-colors.mjs`. Catalogue: R61 FE_STYLE_TOKEN_ONLY (the class-name half of the soft-pair contrast obligation; the brand layer's own contrast is `starci/status-contrast` of @starci/stylelint-canon).
+
+A status tone has two faces. The solid tone (`--success`) is a fill, with `--success-foreground` ink on it. A status shown as text or as an icon takes the soft pair, the way a HeroUI flat Chip does: `--success-soft-foreground` ink, on `--success-soft` when it sits on a tint. The soft pair is what the brand layer is checked to make readable (3:1 on the tint and on the page); the solid tone reads 3.8:1 or worse on white, so as a text colour it fails. The tones are the grammar's status tones (`success`, `warning`, `danger`, `info`), read from `lib/status-tones.generated.mjs`, which is generated from the grammar with the stylelint vocabulary.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/status-text-uses-soft-foreground`
+
+No class that paints text, an icon or a text decoration with a solid status tone: `text-<tone>`, `fill-<tone>`, `stroke-<tone>`, `decoration-<tone>` (with any variant, opacity or `!`), read from `className`/`class`, from `cn()`/`clsx()` arguments, conditionals, arrays, constants and `classes` entries.
+
+**Invalid** (`src/components/leaves/StatusText/index.tsx`)
+
+```tsx
+<span className="text-success" />
+<svg className={cn("size-4", ok && "fill-danger")} />
+```
+
+**Valid** (`src/components/leaves/StatusText/index.tsx`)
+
+```tsx
+<span className="bg-success-soft text-success-soft-foreground" />
+<button className="bg-success text-success-foreground" />
+<div className="border-danger ring-2 ring-warning" />
+```
+
+**Finding code:** `FE_STYLE_TOKEN_ONLY`
+
+**Vì sao (why):** `<file>` tô chữ hoặc icon bằng tông trạng thái đặc (`<what>`, ví dụ `text-success`). Tông đặc là màu nền; dùng làm màu chữ nó đọc dưới 4.5:1 trên nền trang.
+
+**Cách sửa:** Đổi thành cặp mềm: `text-<tông>-soft-foreground` (kèm `bg-<tông>-soft` nếu nằm trên nền nhạt); tông đặc chỉ dùng với `bg-<tông>` và `text-<tông>-foreground`.