# Extend the catalogue

> Add or update a tell: catalogue entry, i18n strings, plain-HTML demo, and alignment with skill taxonomy, detection, and fix references.

- Repository: yetone/kill-ai-slop
- GitHub: https://github.com/yetone/kill-ai-slop
- Human docs: https://grok-wiki.com/public/docs/yetone-kill-ai-slop-c0d8c9670cbb
- Complete Markdown: https://grok-wiki.com/public/docs/yetone-kill-ai-slop-c0d8c9670cbb/llms-full.txt

## Source Files

- `website/src/data/catalogue.ts`
- `website/src/data/catalogue.i18n.ts`
- `website/src/data/demos.ts`
- `skill/references/taxonomy.md`
- `skill/references/detection.md`
- `skill/references/fixes.md`

---

---
title: "Extend the catalogue"
description: "Add or update a tell: catalogue entry, i18n strings, plain-HTML demo, and alignment with skill taxonomy, detection, and fix references."
---

Extending a tell in **yetone/kill-ai-slop** means keeping six surfaces in lockstep: `website/src/data/catalogue.ts` (site + skill catalogue SSoT), `website/src/data/catalogue.i18n.ts` (`ja`/`ko`), `website/src/data/demos.ts` (plain-HTML before→after), `styles/demos.css` (scoped under `.demo-<id>`), and the skill references `skill/references/taxonomy.md`, `detection.md`, and `fixes.md` (plus `scripts/scan.mjs`, which encodes detection patterns). Catalogue copy is numbered by array position; skill docs use matching ordinals (`01`, `02`, …). Inserting an entry renumbers later catalogue `n` values automatically.

## Surfaces to change

| Surface | Path | Role |
| --- | --- | --- |
| Catalogue entry | `website/src/data/catalogue.ts` | Single source of truth for tells: id, tier, group, `title`/`what`/`why`/`fix`, `detect[]`, optional `demo` key |
| JA/KO copy | `website/src/data/catalogue.i18n.ts` | Per-id `ja`/`ko` for `title` \| `what` \| `why` \| `fix`; missing fields fall back to English at the `<T>` layer |
| Demo HTML | `website/src/data/demos.ts` | `Record<string, { before: string; after: string }>` keyed by the catalogue `demo` string |
| Demo styles | `styles/demos.css` | Styles for demos, scoped under `.demo-<id>` |
| Taxonomy | `skill/references/taxonomy.md` | Human taxonomy: 23 tells, two tiers; what / why / fix in prose |
| Detection | `skill/references/detection.md` | Human + widen-able patterns; `scripts/scan.mjs` encodes these |
| Fixes | `skill/references/fixes.md` | Before→after directions (not blind find-and-replace) |

```text
website/src/data/
  catalogue.ts        ← Entry (en + zh inline), Groups, rawEntries → n
  catalogue.i18n.ts   ← ja/ko keyed by entry id
  demos.ts            ← before / after HTML by demo key
styles/
  demos.css           ← .demo-<id> …
skill/references/
  taxonomy.md         ← ###-style **NN · Name**
  detection.md        ← ### NN Name + rg patterns
  fixes.md            ← ### NN Name + diff directions
scripts/
  scan.mjs            ← encodes detection.md patterns
```

<Note>
Earlier catalogue drafts used annotated screenshots of a reference product. Those were removed in favour of live HTML demos so the comparison stays precise and does not drift.
</Note>

## Catalogue entry shape

`catalogue.ts` defines the website catalogue and the spec the skill enforces.

### Types

| Name | Shape |
| --- | --- |
| `Group` | `"color" \| "type" \| "copy" \| "component" \| "layout" \| "evolved"` |
| `Bi` | `{ en: string; zh: string; ja?: string; ko?: string }` — English is always present; `zh` is written inline in `catalogue.ts`; `ja`/`ko` are merged from `catalogue.i18n.ts` |
| `Entry` | `id`, `n`, `tier` (`1` \| `2`), `group`, `title`/`what`/`why`/`fix` as `Bi`, `detect: string[]`, optional `demo?: string` |

`rawEntries` is `Omit<Entry, "n">[]`. Entries are numbered by position in that array; inserting renumbers the rest.

### Required fields when adding a tell

| Field | Constraint |
| --- | --- |
| `id` | Stable kebab-case string used across i18n and demos (e.g. `indigo-violet-gradient`, `mono-hue-alert`) |
| `tier` | `1` classic (widely recognised) or `2` evolved (newer templated defaults) |
| `group` | One of the `Group` keys; drives site grouping via `GROUPS` |
| `title`, `what`, `why`, `fix` | At least `en` and `zh` on each `Bi` in `catalogue.ts` |
| `detect` | Short code-level signal strings (mono chips + skill heuristics), not full `rg` scripts |
| `demo` | Key into `demos.ts` / `.demo-<id>` styles; omit only if there is intentionally no live demo |

### Example entry (from catalogue)

```ts
// website/src/data/catalogue.ts — pattern for a rawEntries item
{
  id: "indigo-violet-gradient",
  tier: 1,
  group: "color",
  title: { zh: "蓝紫渐变", en: "The indigo→violet gradient" },
  what: {
    zh: "从 #6366f1 到 #a855f7 的紫色对角渐变，按钮、光晕、hero 背景，无处不在。",
    en: "That #6366f1→#a855f7 diagonal on buttons, glows, and hero backgrounds.",
  },
  why: { /* en + zh */ },
  fix: { /* en + zh */ },
  detect: [
    "from-indigo-500 to-purple-500",
    "#6366f1 → #a855f7",
    "bg-gradient-to-r via-purple",
    "shadow-purple-500/50",
  ],
  demo: "indigo-violet-gradient",
}
```

### Groups

| `group` | English label (`GROUPS`) |
| --- | --- |
| `color` | Color |
| `type` | Type |
| `copy` | Copy |
| `component` | Components |
| `layout` | Layout |
| `evolved` | Evolved slop |

## Skill ↔ site id alignment

Taxonomy, detection, and fixes are ordered **01–N** with human titles. The site uses **stable string ids**. Keep ordinals, titles, and ids consistent when you insert or reorder.

| Ordinal (skill refs) | Catalogue / demo id (examples) |
| --- | --- |
| 01 Indigo→violet gradient | `indigo-violet-gradient` |
| 02 Gradient headline text | `gradient-text` |
| 03 Warm "cozy" palette | `warm-cozy-palette` |
| 04 Default semantic palette | `default-semantic-palette` |
| 05 One-hue status box | `mono-hue-alert` |
| 07 Serif-italic on one word | `serif-emphasis` |
| 08 Serif where sans belongs | `serif-body-misuse` |
| 09 Decorative strikes & highlights | `decorative-text-lines` |
| 10 Highlighted keywords | `highlighted-keywords` |
| 11 AI copywriting voice | `ai-copy-tics` |
| 12 Emoji everywhere | `emoji-everywhere` |
| 13 Glowing status dot | `status-dot-glow` |
| 14 Rounded card, colored left border | `left-border-callout` |
| 15 Rounded-square icon tiles | `pastel-icon-tiles` |
| 16 Max radius + glassmorphism | `over-rounded-glass` |

Taxonomy states **23 tells** in two tiers. Detection and fixes use the same numbering scheme; detection notes that every match is a **lead, not a verdict**, and that `scan.mjs` encodes the patterns while the markdown is the place to widen stack-specific signals.

## Add a new tell

<Steps>
  <Step title="Define the tell in the shared language">
    Write what it is, why it reads as machine-made (default / absence of a decision), and the clean move. Taxonomy rule: the same element chosen and defended is not slop.
  </Step>
  <Step title="Insert `rawEntries` in `catalogue.ts`">
    Place the object in the correct group section. Supply `id`, `tier`, `group`, `en`+`zh` for `title`/`what`/`why`/`fix`, `detect[]`, and `demo` key when shipping a live comparison. Do not set `n` by hand — position assigns it.
  </Step>
  <Step title="Add JA/KO in `catalogue.i18n.ts`">
    Key by the same `id`. Shape:

```ts
// website/src/data/catalogue.i18n.ts
export interface EntryI18n {
  ja?: LangText; // Partial<record of title|what|why|fix>
  ko?: LangText;
}

// i18n: Record<string, EntryI18n>
"indigo-violet-gradient": {
  ja: { title: "…", what: "…", why: "…", fix: "…" },
  ko: { title: "…", what: "…", why: "…", fix: "…" },
},
```

    Partial translations are safe: missing fields fall back to English at `<T>`.
  </Step>
  <Step title="Add `before` / `after` HTML in `demos.ts`">
    Key must match catalogue `demo`. Styles live under `.demo-<id>` in `styles/demos.css`. Demo copy stays short and neutral.
  </Step>
  <Step title="Update skill references">
    - `taxonomy.md` — new **NN · Name** under the right section (Color / Type / Copy / Components / …), with what, why, and *Fix*.
    - `detection.md` — `### NN Name`, `rg` (or hard-to-grep) signals, false-positive / confirm notes. Scan scope remains frontend extensions listed in that file; skip dirs like `node_modules`, `dist`, lockfiles, `*.min.*`.
    - `fixes.md` — `### NN Name`, directional `diff` examples. Prefer token/theme fixes first, then components, then call sites, then copy.
    - Encode new patterns in `scripts/scan.mjs` to match `detection.md`.
  </Step>
  <Step title="Renumber skill ordinals if you inserted mid-list">
    Catalogue `n` follows array order. Skill files use explicit `01`… labels — keep them aligned with catalogue position after insert/delete.
  </Step>
</Steps>

## Update an existing tell

| Change | Touch |
| --- | --- |
| English or Chinese wording | `catalogue.ts` only (`en` / `zh`) |
| Japanese or Korean | `catalogue.i18n.ts` for that `id` |
| Detection chips on the site | `detect[]` in `catalogue.ts` **and** patterns in `detection.md` / `scan.mjs` |
| Remediation guidance | `fix` copy in catalogue + i18n **and** `fixes.md` |
| Live comparison | `demos.ts` + `.demo-<id>` CSS |
| Rename `id` | Update catalogue entry, i18n key, demos key, `demo` field, and CSS scope together — ids are the join key |

## Copy and voice rules

Catalogue and i18n share one voice contract (site argues against slop, so it must not commit it):

- Terse, plain, specific.
- No punchy three-word triads.
- No “not just X, it’s Y”.
- No exclamation-driven hype.

`what` is one line: what the tell is. `why` explains machine-made defaults. `fix` is the clean move (tokens/components preferred over mass call-site edits — same order as `fixes.md`).

## Demo requirements

`demos.ts` rebuilds each tell in plain HTML:

| Pane | Constraint |
| --- | --- |
| `before` | Illustrates the tell (gradient chrome, emoji chrome, glass pills, etc.) |
| `after` | Held to site/skill rules: one accent, no gradient chrome, hierarchy from scale + space, mono for code only, no decorative emoji/badges |

Example structure:

```ts
// website/src/data/demos.ts
export const demos: Record<string, { before: string; after: string }> = {
  "gradient-text": {
    before: `<h5 class="grad-head">Your changelog, automated</h5>
      <p class="sub">It writes release notes from merged PRs.</p>`,
    after: `<h5 class="solid-head">Your changelog, automated</h5>
      <p class="sub">It writes release notes from merged PRs.</p>`,
  },
  // …
};
```

`after` for copy tells should prefer specifics (numbers, nouns, consequences) over triads and em-dash drama — same direction as fix **11** / id `ai-copy-tics`.

## Detection and fixes alignment

### Detection (`detection.md` → `scan.mjs`)

- Patterns are concrete `rg` (or similar) signals per tell.
- Scope: `.html .css .scss .tsx .jsx .ts .js .vue .svelte .astro .md .mdx` plus `tailwind.config.*`; skip build/vendor/min/lock paths listed in the file.
- Document false positives and “confirm” notes next to the patterns.
- Catalogue `detect[]` should read as short human chips that match the same signals (e.g. `bg-clip-text text-transparent`, not a full multi-line script).

### Fixes (`fixes.md`)

General order of operations:

1. Design tokens / theme (colors, radius, fonts) — many hits disappear at once.
2. Components, then one-off call sites.
3. Copy last.

Fixes are **directions** adapted to the project’s tokens and framework, not mechanical replace-all rules. Cross-link related tells where the playbook already does (e.g. oversized shadow vs purple glow vs status-dot halo).

## Verification checklist

After an add or update:

| Check | Pass signal |
| --- | --- |
| Catalogue | New/updated object in `rawEntries`; `id` unique; `tier`/`group` valid; `en`+`zh` complete |
| Numbering | Site order and skill `### NN` / `**NN ·` labels still correspond after insert |
| i18n | `i18n[id]` present for `ja`/`ko` or intentional English fallback |
| Demo join | `entry.demo` equals a key in `demos` (when set); `.demo-<id>` styles exist for the HTML classes used |
| Demo quality | `after` has no decorative gradient chrome, emoji spam, glass/pill max-radius as the default, or multi-hue keyword highlighting |
| Detection | `detection.md` section exists; `scan.mjs` encodes equivalent signals; false-positive notes written |
| Fixes | `fixes.md` section exists with directional before→after |
| Taxonomy | `taxonomy.md` prose matches catalogue `what`/`why`/`fix` intent |

<Warning>
Do not treat catalogue `detect` chips or scanner hits as verdicts. Detection reference: every match is a lead — open the file and confirm.
</Warning>

## Common failure modes

| Failure | Effect |
| --- | --- |
| New catalogue row without skill ordinals | Field guide shows the tell; skill/scanner language drifts |
| Skill section without catalogue `id` | Agents detect/fix a tell the site does not list |
| `demo` key typo | Missing or empty before/after pane |
| i18n key ≠ `id` | JA/KO never attach; silent English fallback |
| Insert mid-array without renumbering skill files | Wrong tell mapped to wrong detection/fix block |
| Sloppy i18n/demo copy (triads, “not just…”) | Site contradicts its own taxonomy |
| Detection only in markdown, not `scan.mjs` | Human reference and scanner diverge |

## Related pages

<CardGroup>
  <Card title="Catalogue model" href="/catalogue-model">
    How `catalogue.ts` is the single source of truth, how demos and i18n attach, and site vs skill boundaries.
  </Card>
  <Card title="Catalogue and demos data" href="/catalogue-data-reference">
    Field-level shapes for `catalogue.ts`, `catalogue.i18n.ts`, and `demos.ts`.
  </Card>
  <Card title="Slop taxonomy" href="/slop-taxonomy">
    Categories, named signals, and shared language between field guide and skill.
  </Card>
  <Card title="Detection patterns" href="/detection-patterns">
    Code-level signals per tell and how findings map to taxonomy ids.
  </Card>
  <Card title="Remediation playbook" href="/fixes-playbook">
    Per-tell clean fixes and how before/after demos illustrate the preferred outcome.
  </Card>
  <Card title="Run the field guide site" href="/run-field-guide-site">
    Local Astro preview so new entries and demos render on the index.
  </Card>
  <Card title="Contributing" href="/contributing">
    Where to change skill references, scanner logic, catalogue data, or site components without breaking alignment.
  </Card>
</CardGroup>