Przejdź do treści
Biblioteka skilli
Programowanie · Automatyzacja

protowiki-update-codex

/protowiki-update-codex

Prowadzi przez aktualizację ProtoWiki do nowej wersji systemu projektowego Wikimedia Codex: wspólne podniesienie trzech pakietów, porównanie dokumentacji, poprawki w skillach i odświeżenie tokenów.

Repozytorium
protowiki ↗
Licencja
LGPL
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

LGPL, otwarta.

Co robi i kiedy

Prowadzi przez aktualizację ProtoWiki do nowej wersji systemu projektowego Wikimedia Codex: wspólne podniesienie trzech pakietów, porównanie dokumentacji, poprawki w skillach i odświeżenie tokenów.

Wyzwalacze z opisu

update Codexupgrade Codexbump @wikimedia/codex
Oryginalny opis (EN)

How to upgrade ProtoWiki to a new version of the Wikimedia Codex design system — bump the three @wikimedia/codex packages in lockstep, diff the upstream design-codex docs between the old and new release tags, propagate documented changes into the codex-* skills, refresh the vendored token snapshot, then verify. Use when asked to "update Codex", "upgrade Codex", "bump @wikimedia/codex", or pull in a new Codex version.

Jak działa

  1. Steps
  2. Why the skills, not just the package?
Sekcje z nagłówków SKILL.md, w oryginale · 228 linii, 1 271 słów
Podgląd SKILL.md
---
name: protowiki-update-codex
description: How to upgrade ProtoWiki to a new version of the Wikimedia Codex design system — bump the three @wikimedia/codex packages in lockstep, diff the upstream design-codex docs between the old and new release tags, propagate documented changes into the codex-* skills, refresh the vendored token snapshot, then verify. Use when asked to "update Codex", "upgrade Codex", "bump @wikimedia/codex", or pull in a new Codex version.
---

# Updating Codex in ProtoWiki

Codex ships as three packages that must always move together:
`@wikimedia/codex`, `@wikimedia/codex-design-tokens`, and
`@wikimedia/codex-icons`. Upgrading is more than an `npm install` — the
`codex-*` skills under `.agents/skills/` are a hand-curated mirror of the
upstream docs, so a version bump also means **diffing the upstream docs
and propagating real changes into those skills**.

The `codex-*` skills always describe the **current** Codex — they read as
if today's version is the only version. They carry no changelog notes
("new in vX", "as of vX"), so there is no "last synced" marker to keep up
to date. Your diff baseline is simply the version that is **already
installed** before you bump it (step 1).

## Steps

### 1. Find the latest version, and note the current one

```bash
npm view @wikimedia/codex version          # latest available = your target
node -e "console.log(require('./node_modules/@wikimedia/codex/package.json').version)"  # installed = your baseline
npm view @wikimedia/codex-design-tokens version
npm view @wikimedia/codex-icons version
```

The currently-installed version is your diff baseline (the skills mirror
it). The latest available is your target. All three packages normally
publish the same version; if they ever diverge, pin the `@wikimedia/codex`
version and let its dependency on `codex-icons` decide.

### 2. Bump the dependencies

Edit the three entries in [`package.json`](../../../package.json) to
`^x.y.z` (keep them identical), then:

```bash
npm install
```

Confirm the lockfile resolved as expected:

```bash
node -e "const l=require('./package-lock.json'); for (const p of ['@wikimedia/codex','@wikimedia/codex-design-tokens','@wikimedia/codex-icons']) console.log(p, l.packages['node_modules/'+p].version)"
```

### 3. Diff the upstream docs (baseline tag .. target tag)

Diff the version you had installed (step 1 baseline) against the one you
just installed. The upstream repo is mirrored on GitHub at
[`wikimedia/design-codex`](https://github.com/wikimedia/design-codex) with
a `vX.Y.Z` tag per release. Get the file-level diff — no clone needed:

```bash
curl -s "https://api.github.com/repos/wikimedia/design-codex/compare/v<old>...v<new>" -o /tmp/codex-compare.json
node -e "const c=require('/tmp/codex-compare.json'); console.log('commits',c.total_commits,'files',c.files.length); for (const f of c.files) console.log(f.status[0], f.changes, f.filename)"
```

Then inspect the patch for any file of interest:

```bash
node -e "const c=require('/tmp/codex-compare.json'); const f=c.files.find(x=>x.filename==='<path>'); console.log(f.patch)"
```

For a very large diff, clone instead and diff locally:

```bash
git clone --filter=blob:none https://github.com/wikimedia/design-codex /tmp/design-codex
git -C /tmp/design-codex diff v<old>..v<new> -- \
  packages/codex-docs/ 'packages/codex/src/components/**/*.md' \
  packages/codex-design-tokens/src/ packages/codex-icons/src/
```

Where things live upstream:

| Upstream area | What it tells you |
| --- | --- |
| `packages/codex-docs/docs/` | Component guidance, design-token docs, usage prose |
| `packages/codex/src/components/**/*.md` | Per-component prop / slot / event reference |
| `packages/codex-design-tokens/src/application.json` + `src/modes/dark.json` | New / changed / deprecated tokens |
| `packages/codex-icons/src/icons.ts` | New / renamed / removed icon names |
| `CHANGELOG.md` | Human summary; cross-check against the file diff |

### 4. Propagate documented changes into the codex-* skills

Only carry over **documented, user-facing** changes — ignore internal
refactors, build/test churn, and the doc-site version string.

**Write every edit as a description of the current state.** Update the
prose so it reads as though the new version is the only version — adjust
the existing wording, add the new token/icon/prop, remove what's gone. Do
**not** add changelog-style notes like "new in vX", "as of vX", or
"changed in vX"; the git history already records when things changed.

| Diff area | Skill to update |
| --- | --- |
| Component props / slots / events / guidance | [`codex-components`](../codex-components/SKILL.md) + `references/*.md` |
| New / changed / deprecated tokens | [`codex-tokens`](../codex-tokens/SKILL.md) + `references/colors.md` etc. |
| Text style scale / the 9-styles rule | [`codex-typography`](../codex-typography/SKILL.md) (and the copy kept in `codex-tokens/references/typography.md`) |
| Added / renamed / removed icons | [`codex-icons`](../codex-icons/SKILL.md) |
| Cross-cutting usage | [`codex-usage`](../codex-usage/SKILL.md) |
| Design principles, visual style, layout, content guidelines | [`codex-style-guide`](../codex-style-guide/SKILL.md) + `references/*.md` |

Verify any new icon name against the installed package before documenting it:

```bash
node -e "const i=require('@wikimedia/codex-icons'); console.log('cdxIconFoo' in i)"
```

Also regenerate the full icon list at
[`codex-icons/references/icons.md`](../codex-icons/references/icons.md)
(a generated Markdown doc — `Name | Constant | Direction`, grouped A–Z).
Run this from the repo root:

```bash
node -e '
const fs = require("fs");
const icons = require("@wikimedia/codex-icons");
const names = Object.keys(icons).filter(n => n.startsWith("cdxIcon")).sort((a,b)=>a.localeCompare(b));
const direction = v => {
  if (v && typeof v === "object") {
    if ("langCodeMap" in v) return "varies by `langCode`";
    if ("shouldFlip" in v) return "flips in RTL";
    if ("rtl" in v) return "distinct LTR/RTL glyphs";
  }
  return "";
};
const label = n => n.replace(/^cdxIcon/, "")
  .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
  .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
const groups = {};
for (const n of names) { const L = n.replace(/^cdxIcon/,"")[0].toUpperCase(); (groups[L]=groups[L]||[]).push(n); }
let out = "# All Codex icons\n\n" +
  "The complete catalogue of importable icon constants from\n" +
  "`@wikimedia/codex-icons` (" + names.length + " icons). Import any of these and\n" +
  "render through `CdxIcon` — see [`../SKILL.md`](../SKILL.md) for usage,\n" +
  "accessibility, and direction/lang handling.\n\n" +
  "The **Name** column is a readable label derived from the constant. The\n" +
  "**Direction** column flags icons that are not plain strings: _flips in RTL_\n" +
  "(auto-mirrored), _distinct LTR/RTL glyphs_, or _varies by `langCode`_.\n\n" +
  "This file is generated from the installed package. To regenerate it (e.g.\n" +
  "after a Codex upgrade) see the\n" +
  "[`protowiki-update-codex`](../../protowiki-update-codex/SKILL.md) skill.\n";
for (const L of Object.keys(groups).sort()) {
  out += "\n## " + L + "\n\n| Name | Constant | Direction |\n| --- | --- | --- |\n";
  for (const n of groups[L]) out += "| " + label(n) + " | `" + n + "` | " + direction(icons[n]) + " |\n";
}
fs.writeFileSync(".agents/skills/codex-icons/references/icons.md", out);
console.log("wrote", names.length, "icons");
'
```

### 5. Refresh the vendored token snapshot

[`codex-tokens/assets/tokens.css`](../codex-tokens/assets/tokens.css) is a
vendored copy used for quick grepping. It is **not** a plain `cp` of one
file: it is the light `:root` block from `theme-wikimedia-ui.css` followed
by the dark tokens from `theme-wikimedia-ui-mode-dark.css`, re-scoped from
`:root` to `html.skin-theme-clientpref-night` (with `color-scheme: dark;`
injected). Regenerate it:

```bash
node -e '
const fs=require("fs"); const dir="node_modules/@wikimedia/codex-design-tokens/";
const light=fs.readFileSync(dir+"theme-wikimedia-ui.css","utf8").trimEnd();
let dark=fs.readFileSync(dir+"theme-wikimedia-ui-mode-dark.css","utf8")
  .replace(/^\/\*[\s\S]*?\*\/\s*/,"")
  .replace(/:root\s*\{/,"html.skin-theme-clientpref-night {\n  color-scheme: dark;").trimEnd();
const header="/* Copied from @wikimedia/codex-design-tokens/theme-wikimedia-ui.css on <DATE> */\n"+
  "/* Night block re-scoped from theme-wikimedia-ui-mode-dark.css (:root -> html.skin-theme-clientpref-night). */\n\n";
fs.writeFileSync(".agents/skills/codex-tokens/assets/tokens.css", header+light+"\n\n"+dark+"\n");
'
```

Replace `<DATE>` with today's date. Sanity-check: braces balance, both the
`:root` and `html.skin-theme-clientpref-night` selectors are present, and
the Codex banner reads the new version.

### 6. Verify

```bash
npm run build
npm run type-check
npm run lint
```

Then `npm run dev` and smoke-test the surfaces most exposed to Codex
changes:

- Popovers: settings panels (`SettingsPopover`) and the article
  language menu (`ArticleHeader`).
- Search: `Search` (`CdxTypeaheadSearch`).
- Loading: `ArticleLive` (`CdxProgressBar`).
- Icons across chrome header/footer and homepage modules.
- Toggle light/dark theme to confirm token injection in
  [`src/theme.ts`](../../../src/theme.ts) still cascades.
- If any patches are committed, check stock and patched both still render —
  `npm run codex:use-stock` / `npm run codex:use-patch` (see
  [`protowiki-codex-patching`](../protowiki-codex-patching/SKILL.md)).
- Hand-built surfaces that wear Codex classes — if `CdxCard.css` (or another
  mirrored component) changed, diff the installed file and update the
  `html[data-codex-patched]` alias block in that prototype's `*-surface.css`
  (see [`protowiki-codex-patching` → card hover](../protowiki-codex-patching/references/building-for-patches.md#card-hover-through-an-overlay-link-gated-alias-blocks)).

### Regenerate the committed patch

A patch in `patches/codex/` is anchored to the published version you just
replaced, so `npm install` will refuse it after a bump. Re-run
`npm run codex:patch -- <url>`, or run `npm run codex:reset` if
the change has now been released.

### Trialling an unmerged Codex change

See [`protowiki-codex-patching`](../protowiki-codex-patching/SKILL.md): the
committed patch, stock/patched switching, side-by-side deploys, and the rules for
CSS that follows Codex changes.

## Why the skills, not just the package?

ProtoWiki's `codex-*` skills are portable, environment-agnostic mirrors of
the upstream Codex docs (see the prefix-as-contract note in
[`AGENTS.md`](../../../AGENTS.md)). Agents read them via progressive
disclosure instead of opening `node_modules` or the live docs site, so they
drift from reality unless every version bump syncs them. The vendored
`tokens.css` and these skills are the two things `npm install` will *not*
update for you.

Wersje

W bazie nie ma innych skilli o nazwie protowiki-update-codex.

Migawka bazy z 13.11.2026 · wersja paczki 5c3d86b1164a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100protowiki-getting-started
    Wprowadza w repozytorium ProtoWiki: stos Vite, Vue 3, Codex i GitHub Pages, układ kodu i skilli oraz pierwszy krok dla nowej osoby lub agenta.
  • 100protowiki-codex-patching
    Pozwala wypróbować niescaloną zmianę Codex z Gerrita w ProtoWiki i budować interfejs, który ją automatycznie uwzględnia, przełączając node_modules między wersją standardową a załataną.
  • 100prepare-package-release
    Przygotowuje i sprawdza podniesienie wersji wtyczek Rudder w zsynchronizowanych manifestach pakietów oraz odświeżenie wiki CodeAlmanac.
  • 90wikimedia-study
    Stosuje analizę marki Wikimedia do szkiców prezentacji, stron, postów i maili.
  • 100new-release
    Przygotowuje wydanie Graphmem lub podbicie wersji, aktualizuje changelog i synchronizuje wersje wtyczek dla OpenCode, pi, Claude Code i Codex.
  • 100upgrade-devproxy-sample
    Aktualizuje istniejące przykłady Dev Proxy do nowej wersji, wraz ze zaktualizowanymi schematami i dokumentacją.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.