Skip to content

About

Design Tokens, Component specs, Figma links and samples, etc.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MNG Web Design System — Project Folder

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: added scripts/; the homepage template audit was deleted from _archive/. Updated 2026-10-08: added tokens/icons/, logos/ and scripts/logos-export/. Updated 2026-10-09: added figma-exports/mng-ads-export/ and scripts/ads-export/. Updated 2026-10-13: added EXPORT-STANDARD.md; figma-exports/ is now legacy (frozen). Updated 2026-10-14: added components/core/ and scripts/component-export/ (shared component exporter; buttons exported, the legacy buttons export and _archive/ deleted); added tokens/core/, tokens/themes/, tokens/wordpress/, dist/, package.json and scripts/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 to mng_web_ds (Karl); the local folder was renamed to match (~/Github/mng_web_ds). Updated 2026-10-23: added CLAUDE.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/ and scripts/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: added scripts/claude-design-system/ (builds the Design System artifact in Claude from the exports). Updated 2026-10-22: added scripts/icon-font/ (rebuilds the icon CSS and preview from tokens/icons/icons.json).

Names

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.

Folder map

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

Where new files go

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.

Rules

  1. 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.
  2. No copy suffixes. Never create names like file (1).md, file (2).md, file-v2.md, file-final.md or file-copy.md. If a download or sync adds a suffix, rename the file back and remove the older one.
  3. No catch-all output folders. Don't create Claude outputs/, outputs/, exports/ or dated folders. Files go where the map says.
  4. No zips. Save exports unzipped in figma-exports/. Zips duplicate the folder and go stale.
  5. Date changes inside the file, not in the file name (for example "Updated 2026-09-30 for …" near the top).
  6. File names: lowercase-with-hyphens for new files (card-teaser.md). Keep existing names as they are so links in other docs still work.
  7. 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).
  8. Exports follow EXPORT-STANDARD.md. Token JSON is DTCG 2025.10 only; no Figma-import-shaped JSON, layer trees or custom schema formats. Generated files in dist/ are never edited by hand.
  9. Paths in docs are written from this folder's top level (for example tokens/colors/mng-colors-sites.csv).

Working in GitHub

  • Repo: https://github.com/dfmedia/mng_web_ds (branch main; renamed from MNGWebDesignSystem 2026-10-20 and moved from kuscholdMNG to dfmedia; old links redirect).
  • Local copy: ~/Github/mng_web_ds on Karl's Mac (moved 2026-10-14, renamed 2026-10-20; ~/Github also holds for_you_tab_mvp and the mng_apps_*_ds repos). 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 to main.
  • 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_ds as 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 with gh api (REST), then delete the bundle. The old token in .git/claude-credentials (for kuscholdMNG) is retired: don't use it or ask for a new one.
  • Checks. npm run validate before 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_Store files, __pycache__ / .pyc files or zips. .gitignore blocks them.

About

Design Tokens, Component specs, Figma links and samples, etc.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages