JM Family Design System
Governance

Changelog

What moved in the system, when, and why. Each entry groups its changes into Added, Changed, Deprecated, and Removed so consumers can verify against a known baseline.

How changes ship

Most updates are additive — a new token, a new component variant, a clarified anti-pattern. They land continuously and the live site is the source of truth. If something looks different than you remember, this page is the place to check why.

Bigger shifts — a renamed token, a reshaped prop, a change in what a semantic color means — carry an entry in the Decision Log next to the changelog item, so the reasoning travels with the change. If you consume the Agent Kit, re-download when your local version.json is older than 90 days or when a coding agent quotes guidance that doesn’t match the site.

How to read an entry

Each release entry has a date, a headline, and a list of changes tagged by kind. The kinds tell you whether an entry needs action on your side.

  • AddedNew surface that didn’t exist before. Safe to ignore until you need it.
  • ChangedExisting surface moved, was renamed, or had its meaning refined. Usually additive on the existing name; check the entry for specifics.
  • DeprecatedStill works, on its way out. Plan to migrate before the next entry promotes it to Removed.
  • RemovedGone. Should have been Deprecated in a prior release — if it wasn’t, the entry links to the Decision Log explaining why.

Releases

Newest first. Material decisions inside any entry also live in the Decision Log.

  1. First-load polish: nav closed by default, light theme, downloadable SN templates

    Three small but visible defaults landing together from preview feedback. The sidebar nav was opening the current section automatically and leaving others to localStorage, which read as inconsistent on a fresh visit. Theme was honoring prefers-color-scheme on first load, so a dark-mode OS would land users in dark before they had a chance to choose. And the ServiceNow article templates were referenced by filename but not actually downloadable from the page.

    • ChangedSidebar nav: every section is now collapsed by default on first visit, including the section containing the current page. Open/close is a deliberate user action, persisted to localStorage under ds-nav-open. Removes the asymmetry where the active section auto-expanded while inactive ones stayed closed — that was the “some open, some closed” behavior reported from preview.
    • ChangedTheme default: light is now the unconditional first-load theme. The pre-hydration script no longer reads prefers-color-scheme — dark mode is opt-in via the toggle and persisted under ds-theme. Dark is still a first-class option, just not the default for users whose OS happens to be in dark mode.
    • AddedServiceNow Articles: each of the five article types (How-to, Reference, Troubleshooting, Policy, FAQ) now ships a download button for its template. Files are served from /templates/*.md. Replaces the inline code labels that hinted at filenames without exposing the files. Matches the canonicalButtonLink pattern, not a one-off download style.
    • ChangedFooter feedback link: points to sergio.urrunaga@jmfamily.com with a pre-filled subject (“Design System Feedback”). Was previously a placeholder designsystem@company.com that didn’t go anywhere.

  2. MCP server v1 fully scoped (no code yet — ready to build)

    Closed the loop on the MCP server scoping pass. All six open questions are resolved: distribution (public NPM), client reach (Claude Desktop + Claude Code CLI + everyone-but-claude.ai-web), the antipatterns code-checker (cut from v1), draft component handling, search ranking for tokens and components, and a written semver rule. The spec is now the final v1 design — the next PR can start the build.

    • Addedspecs/MCP_SERVER.md — v1 scoping doc. Covers why MCP over REST, the architecture (single data layer, MCP as first transport, REST optional later), the tools and resources per artifact, distribution via public NPM as @jmfamily/ds-mcp-server, which clients v1 reaches (Claude Desktop, Claude Code CLI, Cursor, Cline, etc.) vs. wait for v1.5 (claude.ai/web), versioning rules (semver with pre-1.0 grace), first-client validation criteria, and what’s explicitly out of scope.
    • AddedDecision Log entry mcp-as-primary-agent-surface — captures the rationale for choosing MCP over a conventional REST/GraphQL API: every modern AI dev tool already speaks MCP, so writing the server once gives the entire agent ecosystem DS-awareness for free, while keeping the data layer open for a future REST surface.
    • ChangedRoadmap "Later" phase: hosted HTTP MCP server promoted into the MCP v1.5 milestone (rather than its own v2 entry). claude.ai/web users get covered as part of the next MCP cycle, not a separate later push.
    • Removedantipatterns.check (code-checker tool) — cut from v1 scope entirely. Was originally a stretch goal; it would have added heuristic brittleness that drags trust in the whole server. May revisit in v1.5 once the read-only surface is established.

  3. Tokenize the de facto letter-spacings (0.04em, 0.06em)

    The previous typography audit estimated ~25 hardcoded letter-spacing em values; the real count was 86 across the codebase. Two values (0.04em and 0.06em) accounted for 79 of those — clearly de facto tokens. Promoting them to real tokens, and fixing a small documentation drift on the Brand → Typography page.

    • AddedTwo new entries on the global font.letterSpacing scale (source: tokens/global/typography.json): subtle at 0.04em (the dominant small-label tracking pattern across the system) and tracked at 0.06em (secondary for shorter eyebrows and chip-like labels). They sit between the existing wide (0.025em) and widest (0.1em — the canonical type.overline tracking). The build pipeline generates --font-letterspacing-subtle and --font-letterspacing-tracked as CSS custom properties.
    • Changed79 hardcoded letter-spacing em values across 44 CSS modules swapped for the new tokens. 54 instances of 0.04em → --font-letterspacing-subtle; 25 instances of 0.06em → --font-letterspacing-tracked. Removed the redundant token-audit-ignore-line comments that had been pasted alongside the hardcoded values.
    • ChangedBrand · Typography: corrected the type.overline letter-spacing in the type-scale table. Was documented as 0.025em, but the underlying token is 0.1em, which is what the live example was actually rendering. Doc table now matches the token.
    • ChangedSeven outliers (5× 0.08em, 1× 0.02em, 1× 0.01em) remain hardcoded. Not promoted to tokens — too few instances to justify, and each is a one-off treatment in a single context. If the 0.08em pattern grows, it earns a token next.

  4. Typography self-conformance pass: mono off labels

    Continuation of the typography audit. Removed the mono font (--type-code-family) from 13 label / eyebrow / placeholder classes across the home page and the Brand pages where it had crept in. Mono now sits only on actual code blocks, inline code, file-format chips, and measurement values — matching what Brand → Typography publishes.

    • ChangedHome page: .eyebrow / .sectionEyebrow consolidated onto thetype.overline tokens; .sceneLabel, .metricValue, and .previewHeader drop mono in favor of the Inter sans default.
    • ChangedBrand · Imagery: .galleryTag,.principleNumber, .meterLabels,.compareImgPlaceholder, and .altRowLabel all drop mono.
    • ChangedBrand · Logo: .systemPreviewMissing,.swatchPreviewMissing, .swatchMeta, and.minimumTreeSymbol all drop mono. .formatChip,.clearSpaceMarker, and .minSizeLabel span keep mono — file extensions and dimensional measurements count as technical content.

  5. Pattern library opens with Empty State, Form Layout, Navigation Shell, Data Table

    The Pattern library moves from queued to in motion. The Overview page frames what a pattern is, and the first four pattern pages ship together so pilot teams have composed UI to follow, not just primitives.

    • AddedPatterns Overview — what a pattern is (composition of primitives and tokens, not a new primitive), the four catalog entries with status, a reach-or-build decision rule, and the six sections every pattern page teaches.
    • AddedEmpty State — the first concrete pattern. Three types (first-run, no-results, absent), anatomy with required vs. optional parts, wrong-vs-right examples, voice and content rules, accessibility, implementation notes.
    • AddedForm Layout, Navigation Shell, and Data Table pattern pages — composed UI for the shapes pilot teams reach for most often.
    • AddedAI Guardrails at /ai-toolkit/guardrails — when AI may ship, what stays with a human, and the sanctioned tools list.
    • ChangedSidebar nav sections collapse when active so the active section can be hidden after the user has navigated into it; reduces visual noise on long catalog pages.

  6. Governance restructure and roadmap re-anchor

    Governance is reshaped around the sole-owner reality of the system. Contribute leads with intake; Review Process and Versioning come out; the Roadmap is rewritten around MCP server and a DS-aware lint plugin as the two leverage bets.

    • ChangedHow to Contribute reframed as intake-first. Teams/email is the primary path; the GitHub contributor flow lives in a brief “If you have repo access” section at the bottom that absorbed the validation-gate list (tooling that runs before review).
    • Removed/governance/review — as sole owner, an internal-process page documented for an audience of one. The useful piece (what the tooling catches) moved into Contribute.
    • Removed/governance/versioning — philosophical framing without a track record yet. The Agent Kit re-download cadence stays on the Agent Kit page; the “How changes ship” framing landed at the top of this page.
    • RemovedSix sidebar stubs from AI Toolkit (Prompt Library, Approved Tools, Submit a Prompt) and Resources (Figma Libraries, FAQ, Glossary). Each was either out of scope or premature; "coming soon" placeholders imply a roadmap commitment the system isn’t making.
    • ChangedRoadmap rewritten around the two leverage bets for 2026: MCP server (queryable resources for coding agents) and a DS-aware lint plugin (enforces conformance at consumer compile time). Now phase tracks Wave 1 carryovers plus MCP kickoff; Next holds the lint plugin, more primitives, and the Pattern library scope.

  7. Content, component docs, and tooling polish

    Several smaller improvements that close gaps without changing the system’s shape. ServiceNow content standards reach the site, every component page now teaches adoption decisions, code snippets get copy buttons, and tooltip placement actually works.

    • AddedServiceNow Articles page surfaces the knowledge-article standards that had landed in content/ but were never reachable from the site. Covers the two-reader model (employee + Ask Hubert), five article types, non-negotiables for retrieval, and the pre-publish checklist.
    • ChangedAll 14 component pages now route through ComponentGuidance — the decision-oriented frame (when to use / when not to use / accessibility / content guidance / implementation notes). API surfaces are auto-derivable; the judgment call is what saves consumer-team engineering time.
    • AddedCopy buttons on every ComponentGuidance import card and baseline code example, so consumers can grab a snippet without manual select-and-copy.
    • ChangedTooltip placement story: directional arrows on the base component, demos use the actual placement prop, tooltips anchor to the trigger (not the demo card), demo frames no longer clip overflowing tooltips, and the known-limitation copy correctly says the gap is no collision detection — not no positioning.
    • ChangedWorkflow stage callouts (“What you carry into the next stage”) brought in line with our published typography rules: type.overline tokens for the eyebrow, Inter (not mono) for the label, no italic on whole-paragraph bodies.
    • ChangedPagefind search works in next dev too. build:search now copies the index from out/pagefind/ into public/pagefind/ after building, so the dev server serves it. Run npm run build once to populate; refresh by rebuilding.

  8. Wave 1 expansion: anti-patterns, motion, decision log

    A teaching-heavy release that fills in the foundations a reviewer or coding agent needs to defend a UI decision. Everything is additive — nothing previously shipped changed shape.

    • AddedAnti-Pattern Catalog at /foundations/anti-patterns — 13 entries across 9 categories, with the principle being violated and the correct alternative documented for each.
    • AddedMotion foundation at /foundations/motion — purposes, principles, live demos, and a global prefers-reduced-motion respect rule in globals.css.
    • AddedDecision Log at /governance/decisions — ten ADR-style entries capturing the reasoning behind settled questions in the system.
    • AddedSTRATEGY.md, ANTI_PATTERNS.md, MOTION.md, and DECISION_LOG.md specs under /specs/ as the source-of-truth documents the web pages render against.
    • ChangedIconography moved from /brand/iconography to /foundations/iconography. Treated as a taxonomy adjustment — the page content is the same, the location reflects that iconography is a foundation, not a brand asset.
    • ChangedBuild pipeline extended: anti-pattern and principles JSON now ship in the Agent Kit export alongside tokens and the Markdown directives.

How entries land

A changelog entry ships with the PR that introduces the change, not as a separate paperwork pass. The author writes the headline, summary, and item list inline; the reviewer treats the entry as part of the change being reviewed. If you can’t describe what changed in one short headline, the PR is probably doing too much.

The entry format is meant to be skimmable. The headline gives the gist; the summary gives the why; the items tell consumers what to do — usually nothing.

Related

  • Decision Log — the durable reasoning behind anything that overrides a prior choice.
  • Roadmap — what’s next on the schedule.