Folder map and filing rules. Every session working on this project reads this first and follows it. Set up 2026-09-30, when duplicate copies made by different sessions were removed. Updated 2026-10-01: the project moved from Google Drive to GitHub (now
kuscholdMNG/mng_web_ds). See "Working in GitHub" below. Updated 2026-10-02: addedscripts/; the homepage template audit was deleted from_archive/. Updated 2026-10-08: addedtokens/icons/,logos/andscripts/logos-export/. Updated 2026-10-09: addedfigma-exports/mng-ads-export/andscripts/ads-export/. Updated 2026-10-13: addedEXPORT-STANDARD.md;figma-exports/is now legacy (frozen). Updated 2026-10-14: addedcomponents/core/andscripts/component-export/(shared component exporter; buttons exported, the legacy buttons export and_archive/deleted); addedtokens/core/,tokens/themes/,tokens/wordpress/,dist/,package.jsonandscripts/build-tokens/(open item 11, step 2; merged 2026-10-14, pull request #2); renamed from "MNG Design System" to MNG Web Design System (see "Names" below); local copy moved to~/Github/. Updated 2026-10-20: GitHub repo renamed tomng_web_ds(Karl); the local folder was renamed to match (~/Github/mng_web_ds). Updated 2026-10-23: addedCLAUDE.md(how Claude works in this project: session start, rules, Figma files; replaces the long Claude project instructions and the status doc's standing rules). Updated 2026-10-27: added.github/workflows/validate.yml,scripts/validate/andscripts/build-tokens/save-snapshot.py(Seth's issue #7: checks on every push; the Figma snapshot is saved only by the script); the GitHub token needs the Workflows permission. Updated 2026-10-29: addedscripts/claude-design-system/(builds the Design System artifact in Claude from the exports). Updated 2026-10-22: addedscripts/icon-font/(rebuilds the icon CSS and preview fromtokens/icons/icons.json).
The design system was renamed on 2026-10-14 (Karl). Use these forms everywhere:
| Where | Form |
|---|---|
| Prose, docs, Figma file name and labels | MNG Web Design System |
| GitHub repo and local folder (renamed 2026-10-20) | mng_web_ds (kuscholdMNG/mng_web_ds, ~/Github/mng_web_ds) |
| Claude project, anything else without spaces | MNGWebDesignSystem |
Code identifiers, the dist/ package name, snake_case contexts |
mng_web_design_system |
| Status file | MNG-Web-Design-System-Status.md |
Not renamed on purpose: the frozen legacy exports in figma-exports/ (including the folder mng-design-system-export/ and its mng-design-system/...@1 schema names), because other projects may point at them; dated historical labels such as "per MNG Design System 2025.07.16" in Figma; the CSS variable prefix --mng- and the DTCG extension namespace com.mng, which name the company, not the system.
mng_web_ds/
├── README.md ← this file
├── CLAUDE.md ← instructions for Claude: session start, standing rules, Figma files
├── .gitignore ← keeps .DS_Store, zips and credentials out of the repo
├── .github/workflows/validate.yml ← GitHub check on every push and pull request: rebuild matches, validate.py
├── MNG-Web-Design-System-Status.md ← project status (the entry point)
├── EXPORT-STANDARD.md ← format rules for every token and component export (DTCG)
├── design-vs-production.md ← production gaps for Engineering
├── Reader-Dashboard-Library-Impact-Map.md
├── components/ ← component audits and checklists (.md), plus the exports:
│ ├── core/<slug>/ ← <slug>.md spec, <slug>.tokens.json, <slug>.html skeleton, previews/
│ │ (buttons: 8 families, 2026-10-14)
│ ├── wordpress/<slug>/ ← same layout, for WordPress Elements components
│ └── index.json ← every exported component (generated)
├── package.json ← makes dist/ installable (package mng_web_design_system)
├── tokens/
│ ├── core/ ← DTCG core tokens: color, typography, spacing, breakpoint
│ │ (generated by scripts/build-tokens/make-tokens.py)
│ ├── themes/ ← one DTCG file per theme, sub-theme and product, sites/ (site
│ │ overrides) and mng.resolver.json (theme → sub-theme → site)
│ ├── sites/ ← one resolved DTCG color file per publication (97, every site in the
│ │ cluster audit) + index.json (theme > cluster > sub-theme > site);
│ │ generated by scripts/build-tokens/make-tokens.py
│ ├── wordpress/ ← WordPress layer: editorial type styles, type-theme/ (font.theme.*
│ │ per theme), WordPress grid breakpoints
│ ├── colors/ ← 2026-10-01 color export: .tokens.json (input for make-tokens.py),
│ │ .css, sites .csv and fixes .csv checklist (generated by
│ │ scripts/colors-docs/), decision
│ │ log, README (color fixes: entry 5).
│ │ Replaced by core/ + themes/; retired in open item 14, step 3
│ ├── typography/ ← typography tokens + decision log
│ ├── breakpoint-inventory.json ← production breakpoints in MNG code, classified (official /
│ │ component / drift), from scripts/breakpoint-inventory/
│ └── icons/ ← production icon font (icomoon .ttf/.woff/.woff2), glyph map,
│ CSS and preview
├── logos/ ← newspaper logos: transparent SVGs (publications/, placeholder/),
│ logos.json manifest, preview.html, README, missing-logos.md (what Marketing still owes)
├── figma-exports/ ← LEGACY, frozen 2026-10-13: older Figma → spec exports.
│ Kept, not updated; new exports follow EXPORT-STANDARD.md
│ ├── mng-design-system-export/ ← homepage, menus-and-parts, form-fields
│ └── mng-ads-export/ ← WordPress Elements Ad Blocks set (ad slots, 37 variants;
│ RevContent excluded)
├── dist/ ← GENERATED from tokens/ by scripts/build-tokens/build.py: CSS, Sass,
│ JS/TS, Tailwind v4 + v3, WordPress theme.json, flat JSON. Never edit
└── scripts/ ← generators that rebuild exports, one folder per export
├── build-tokens/ ← extract.js (Figma plugin code) → save-snapshot.py → figma-variables.json
│ → make-tokens.py (tokens/) → build.py (dist/, with checks)
├── validate/ ← validate.py (npm run validate; EXPORT-STANDARD §10) + pre-commit hook
├── ads-export/ ← extract.js (Figma plugin code) + build-ads-export.py
├── colors-docs/ ← build-color-docs.py (per-site CSV, mng-colors.css and entry 5 of
│ design-vs-production, from mng-colors.tokens.json) + notes.json
├── breakpoint-inventory/ ← scan.js (live CSS scan in Chrome) + scans/ + build-inventory.py
├── icon-font/ ← build.py (tokens/icons/icomoon.css and preview.html, from icons.json)
├── claude-design-system/ ← build.py + src/ (component code, previews, README prose): the
│ MNG Web Design System artifact in Claude (link in the status doc)
├── component-export/ ← shared component exporter: extract.js (Figma plugin code) +
│ registry.json (which components, hand-checked text) + export.py
├── design-system-export/ ← extract.js + build-design-system-export.py + curated.json
│ (hand-checked notes) + save-previews.py
└── logos-export/ ← build-logos.py + sources.json (publication → .ai file) +
extract-placeholders.js + figma-placeholders.json
| What you made | Where it goes |
|---|---|
| Project status update | Edit MNG-Web-Design-System-Status.md in place |
| A new design-vs-production gap | Add an entry to design-vs-production.md |
| Component export (spec, component tokens, skeleton, previews) | Add the component to scripts/component-export/registry.json, run extract.js in Figma, then export.py. Writes components/<layer>/<slug>/. |
| Component audit or checklist | components/<component-name>.md |
| Token values (color, type, spacing, radius, shadows, breakpoints) | Change Figma (shadows are the shadow/* effect styles), rerun scripts/build-tokens/extract.js and save it with scripts/build-tokens/save-snapshot.py (never by hand; CLAUDE.md, Exports), then npm run build and npm run validate. Writes tokens/core/, tokens/themes/, tokens/wordpress/ and dist/. On a review/... branch with a pull request. |
| Color decisions, sites CSV | Decisions: tokens/colors/color-tokens-decision-log.md. Color values and production mismatches: tokens/colors/mng-colors.tokens.json, then run scripts/colors-docs/build-color-docs.py (rewrites the sites CSV, mng-colors.css and the per-site part of entry 5; notes per theme in scripts/colors-docs/notes.json) and npm run build. |
| Typography tokens or decisions | tokens/typography/ |
| Icon font, glyph map, icon previews | tokens/icons/ (edit icons.json, then run scripts/icon-font/build.py to rebuild icomoon.css and preview.html) |
| Newspaper logo SVGs, manifest, preview | logos/ (rebuilt by scripts/logos-export/build-logos.py; don't hand-edit the SVGs) |
| Missing newspaper logos (what to ask Marketing for) | Update logos/missing-logos.md in place |
| A token or component export | Follow EXPORT-STANDARD.md (DTCG .tokens.json, layers, dist/). Never add to figma-exports/ (legacy). |
| A script that rebuilds an export | scripts/<export-name>/ (inputs and outputs explained at the top of the script) |
| The Design System artifact in Claude (components, previews, guidance) | scripts/claude-design-system/src/; rebuild with build.py --out <folder outside the repo> and republish (that folder's README) |
| Anything no longer current | Delete it. Git history keeps every old version. |
- One file per topic. Before writing, check if a file for that topic already exists. If so, update it in place. Never save a second copy next to it or in another folder.
- No copy suffixes. Never create names like
file (1).md,file (2).md,file-v2.md,file-final.mdorfile-copy.md. If a download or sync adds a suffix, rename the file back and remove the older one. - No catch-all output folders. Don't create
Claude outputs/,outputs/,exports/or dated folders. Files go where the map says. - No zips. Save exports unzipped in
figma-exports/. Zips duplicate the folder and go stale. - Date changes inside the file, not in the file name (for example "Updated 2026-09-30 for …" near the top).
- File names: lowercase-with-hyphens for new files (
card-teaser.md). Keep existing names as they are so links in other docs still work. - Retiring a file: delete it, then update any docs that mention its path. Git history keeps every old version, so there is no
_archive/folder: old versions aren't kept while the file formats are still being settled (Karl, 2026-10-14). - Exports follow
EXPORT-STANDARD.md. Token JSON is DTCG 2025.10 only; no Figma-import-shaped JSON, layer trees or customschemaformats. Generated files indist/are never edited by hand. - Paths in docs are written from this folder's top level (for example
tokens/colors/mng-colors-sites.csv).
- Repo: https://github.com/dfmedia/mng_web_ds (branch
main; renamed fromMNGWebDesignSystem2026-10-20 and moved fromkuscholdMNGtodfmedia; old links redirect). - Local copy:
~/Github/mng_web_dson Karl's Mac (moved 2026-10-14, renamed 2026-10-20;~/Githubalso holdsfor_you_tab_mvpand themng_apps_*_dsrepos). Work only there. The old Google Drive folder is retired; don't save anything to it. - Commit every change with a short message that says what changed and why (for example "Add card-teaser hover states"). Git history replaces the dates in file names, so rule 5 still applies: put the date inside the file.
- Value changes that need Karl's review (token values, decisions in the decision logs) go on a branch, such as
review/primary-blue-fix, with a pull request. Everything else can go straight tomain. - Push after committing. Claude pushes from its cloud session, which has access to
dfmedia/mng_web_ds(Karl, 2026-11-05): commit in~/Github/mng_web_dsas usual, bundle the new commits (git bundle create .export-tmp/push.bundle origin/main..<branch>, with.export-tmp/excluded in.git/info/exclude), bring the bundle into the cloud session, push from there, open pull requests withgh api(REST), then delete the bundle. The old token in.git/claude-credentials(forkuscholdMNG) is retired: don't use it or ask for a new one. - Checks.
npm run validatebefore committing (the pre-commit hook runs it once installed:cp scripts/validate/pre-commit .git/hooks/pre-commit). GitHub runs the same check on every push; keep it green. - Never commit credentials,
.DS_Storefiles,__pycache__/.pycfiles or zips..gitignoreblocks them.