Decision Log

Once the educational-mission-and-ai-moat positioning was settled and mcp-server-and-lint-plugin-as-2026-bets confirmed MCP as one of the two leverage bets, the practical question was: REST API or MCP, and is there a way to keep optionality. A REST API is the conventional surface and serves both AI and non-AI consumers; MCP is the AI-first surface with zero per-client integration cost but awkward for non-AI callers like CI scripts.

Build an MCP server as the primary AI consumption surface. Design the data layer (existing JSON sources under tokens/, data/, src/lib/component-registry.ts) so a REST API can sit on top later as a separate transport without rework. Local stdio binary for v1 distribution; hosted HTTP comes when there's a reason for it (telemetry, browser clients, CI).

Every product team at JMF using an AI dev tool to write code is a potential beneficiary of a DS-aware agent, and the cost of making them DS-aware is zero per consumer once the MCP server exists. A REST API would require either each agent vendor to write a custom integration (unlikely) or each product team to manually wire tool-use schemas in their app code (high friction, doesn't scale). MCP turns one Sergio-month into permanent multiplier value across the entire agent ecosystem; the trade-off is non-AI consumers (CI scripts, internal dashboards) keep using the Agent Kit ZIP for now and get a proper REST surface in v3 if and when the demand is concrete.

• Build a REST API first, MCP wraps it later (rejected: postpones the leverage benefit; in the meantime every AI tool needs custom integration; conventional but slower to deliver the strategic moat).
• MCP only, never REST (rejected: forecloses optionality for non-AI consumers; even if we don't need REST today, the data layer is the long-lived asset and shouldn't be coupled to one transport).
• Scrape-the-site / Agent Kit ZIP only (rejected: scraping is noisy and stale-prone; the ZIP works for code-level consumers but doesn't give agents a query surface, so every consumer reinvents the same parsing logic).

• v1 ships as a local stdio binary distributed internally; hosted HTTP is a v2 decision.
• The data layer (JSON under tokens/, data/, src/lib/) becomes the long-lived design: the MCP server is the first transport, not the source of truth.
• Non-AI consumers (CI conformance checks, internal dashboards, Figma plugin if it ever returns) wait until phase 3 for a REST surface, or pull the Agent Kit ZIP in the meantime.
• Maintaining the MCP server adds a build artifact (and a small surface area for breaking changes) to the system.
• The v1 scope (tokens + components + anti-patterns) is intentionally narrow; principles, decisions, voice & tone, ServiceNow standards land in v1.5.

The pre-2026-05-20 roadmap had drifted to Wave 1-era items (search, governance pages, Voice & Tone, microinteractions, asset library), most of which had already shipped or were trivially in flight. With a sole owner and a backlog of plausible directions (more components, patterns, MCP, lint plugin, conversational mode, Agent Kit npm, Hub integration, adoption dashboard), the question is which moves multiply rather than add.

Center the 2026 roadmap on MCP and the lint plugin. Now phase: MCP server kickoff alongside Wave 1 carryovers (editorial export for Ask Hubert, per-component conformance cards). Next: DS-aware lint plugin, more component primitives, Pattern library. Later: Agent Kit as an npm package, conversational mode (Ask Hubert), page templates.

Both bets turn one Sergio-month into permanent multiplier value: MCP makes every existing token / component / anti-pattern / decision queryable by agents (one investment, every future agent benefits); the lint plugin enforces conformance at consumer compile time (one investment, every product team that installs it stays in pattern). Components and patterns grow naturally because pilot-team work demands them; AI-leverage items don't build themselves.

• Keep growing components linearly (rejected: doesn't differentiate the system from any other component library).
• Lead with conversational mode / Ask Hubert (rejected: depends on the editorial export, which is itself a downstream piece).
• Ship Agent Kit npm package first (rejected: MCP is the bigger architectural decision; npm packaging follows naturally once consumers are pulling the kit programmatically).

• Components and patterns shipped opportunistically as background work, not as a separate strategic line.
• Conversational mode (Ask Hubert) sequenced after the editorial export lands.
• Agent Kit npm packaging queued for after MCP is live and the kit's role in the consumption flow is settled.
• Hub integration drops off the roadmap entirely. It was on the earlier Later list but not picked up as part of the 2026 anchor.

A strategic review of the product surfaced the question: what makes this design system worth investing in versus the many that already exist? Documentation-first design systems are a saturated category. Solo-builder constraints rule out scaling through headcount. The Agent Kit had already been validated at the 2026 hackathon as a meaningful UI accelerator.

Frame the design system around two load-bearing pillars: (a) an explicit educational charter (raise design quality across JMF by teaching, not by enforcing) and (b) AI agents as first-class consumers via a planned MCP server, alongside the human-facing site.

The combination is differentiated: most design systems are documentation-first, not generation-and-critique-first. An educational charter justifies investment in content quality (rationale, anti-patterns, decision logs) that competitors don't ship. An agent-first orientation compounds the value of every artifact, because each piece of guidance can be queried by both humans and AI workflows.

• Pure component-library product (rejected: no defensible position; saturated category).
• Figma-led design system (rejected: minimal internal Figma adoption; see figma-out-of-scope).
• Internal-tools-only without external positioning (rejected: under-leverages the AI-agent angle that's already proven).

• Content quality becomes the top investment, not component count.
• Roadmap re-sequenced to put content depth first, MCP second, distribution third (see content-depth-before-mcp).
• Justifies durable artifacts like the Decision Log and Anti-Pattern Catalog that pure component libraries skip.

Initial strategic recommendations included Figma Tokens Studio sync as a Q2 deliverable, the standard playbook for design systems. But internal Figma usage at JMF is minimal, and Sergio has largely abandoned the tool. Investment would be effort against a tool nobody uses.

Figma is explicitly out of scope. No bidirectional sync, no plugin, no Figma-shaped APIs. Designer-facing tooling, when needed, will live in the site itself or in code-first workflows.

Strategy is as much about what you don't do as what you do. Building Figma integrations because everyone else does, when JMF doesn't actually use Figma, would burn the limited solo-builder budget on tooling that produces no return.

• Tokens Studio plugin sync (rejected: JMF doesn't use Tokens Studio).
• Figma file embeds on component pages (rejected: designers consuming this are not in Figma).
• Hybrid: ship Figma support if any team requests it (deferred indefinitely; if a team commits, we revisit).

• Distribution focuses on NPM tokens, MCP, asset library, and editorial export, not designer tooling.
• Reduces scope of every quarter's roadmap by deleting a class of work.
• If JMF Figma adoption changes materially, this decision needs revisiting.

Initial framing assumed a single distribution: an NPM package teams pull. But the actual consumer landscape is varied: The Hub needs brand assets and principles; Ask Hubert (a Copilot Studio agent) needs voice and editorial guidance; prototypes need tokens and components. One delivery shape can't serve all three.

Recognize three first-class consumption modes (reference + assets, conversational, and code) and design distribution per mode. Same upstream source of truth, three downstream surfaces.

Each mode has a different success metric (asset downloads, agent-answer quality, token coverage in consumer code) and a different delivery format (downloadable files, structured JSON / SharePoint, NPM package). Treating them uniformly under-serves all three.

• Single NPM package (rejected: wrong shape for non-code consumers like The Hub).
• Figma-led distribution (rejected per figma-out-of-scope).
• Postpone distribution decisions to Q3 (rejected: leaves Q1 directionless).

• Roadmap includes three parallel distribution workstreams: asset library, editorial export, tokens NPM.
• Metrics segmented by mode (see STRATEGY.md §8).
• Justifies content investments that benefit specific modes (Voice & Tone for Ask Hubert).

Initial roadmap put the MCP server in Q1 as the 'headline' AI-agent feature. But the MCP exposes content that doesn't exist yet: motion guidance, anti-patterns, editorial rules. A hollow MCP would launch with stubs and embarrass the strategic differentiator.

Q1 focuses on content depth and one artifact per consumption mode (asset library v1, editorial export draft, anti-pattern catalog). MCP moves to Q2, built on the depth Q1 produces.

A hollow MCP serves no one. The Agent Kit was already validated at the hackathon, which removes the urgency to ship MCP just to prove the AI-agent thesis. Content quality is upstream of every other investment: the MCP, the teaching agent, the agent kit all draw from it.

• MCP first as a headline launch (rejected: hollow content makes the MCP a demo, not a product).
• Parallel MCP + content tracks (rejected: solo builder can't run two depth-investments simultaneously).
• Skip content depth and ship MCP with placeholders (rejected: undermines the educational charter).

• Anti-Pattern Catalog and Motion foundation shipped first as content depth.
• MCP architecture work deferred until Q2.
• Agent Kit validation from hackathon does double duty: it proved the thesis and removed the pressure to ship MCP fast.

Strategic review surfaced that the roadmap was theoretical without a named pilot. Generic 'JMF teams will benefit' framing makes every quarter's milestones unfalsifiable. The Agent Kit had already been used at the 2026 hackathon by Sergio's team with measurable benefit. There was a real anchor consumer hiding in plain sight.

Inform & Engage is the first-adopter team. Distribution decisions (package format, MCP hosting, conformance scope) prioritize this team's products: The Hub (reference + assets), Ask Hubert (conversational), and the hackathon-style prototypes (code).

An internal team Sergio sits inside guarantees access, removes onboarding friction, and covers all three consumption modes naturally. The hackathon validation is real proof, not a pitch.

• External team pilot (rejected: slower onboarding, no existing trust).
• No pilot until Q2 (rejected: Q1 needs a target to ship against).
• Multiple pilot teams in parallel (deferred: start with one and expand).

• Q2 and Q3 milestones now have concrete acceptance: Ask Hubert pulling editorial export, prototypes pulling @jmf/tokens.
• If Inform & Engage's product priorities shift, the design system's roadmap may need to follow.
• Establishes a pattern: every consumption mode needs a named pilot before it's resourced.

AI Toolkit listed Prompt Library, Approved Tools, and Submit a Prompt: all 'coming soon' stubs. Approved Tools isn't governed by the design system at all (IT owns it). Resources listed Figma Libraries, FAQ, and Glossary. The first contradicts the existing No Figma decision; the latter two were aspirational without any real consumer signal. Leaving stubs in nav implies a roadmap commitment the system isn't making and clutters the catalog.

Remove from src/lib/navigation.ts: ai-toolkit/{prompts, tools, submit} and resources/{figma, faq, glossary}. AI Toolkit reduces to Agent Kit + AI Guardrails; Resources reduces to Templates & Checklists + Asset Library. Also update the get-started/introduction AI Toolkit card so it points at Agent Kit (the only built page in the section) and drops the description language that referenced the removed items.

Coming-soon stubs are an implicit promise. Promises the system isn't going to keep erode trust faster than missing items would. Patterns is left intact (5 stubs) because it's an actively planned wave with concrete shape; AI Toolkit and Resources stubs were inherited optimism, not plans.

• Keep the stubs and ship the pages eventually (rejected: no concrete plan to ship Prompt Library / FAQ / Glossary; Figma is permanently out of scope).
• Add a 'planned' state alongside 'coming soon' (rejected: same problem with no real timeline).

• Sidebar lighter and more honest about what the system covers.
• Direct visits to the removed paths return 404; spec docs still reference the old shape (separate cleanup).
• Future re-introduction is a normal change with a real ship date, not a recovery from a broken promise.

When adding the Anti-Pattern Catalog, three placements were on the table: Foundations > Anti-Patterns (recommended), a new top-level Anti-Patterns section paired with Patterns, or Resources > Anti-Patterns (a reference manual).

Place Anti-Patterns under Foundations as the third entry, after Color System and Design Principles.

Anti-patterns are foundational quality guidance: they teach what bad design looks like, which is the same kind of knowledge as design principles. Putting them near Design Principles and Accessibility makes them discoverable for the user already in the right mental mode. A new top-level section would have added L1 nav weight for content that conceptually belongs with existing foundations.

• Top-level Anti-Patterns as a peer to Patterns (rejected: adds an L1 nav item; would make 'Patterns' and 'Anti-Patterns' look like opposites when they're actually different concepts).
• Resources > Anti-Patterns (rejected: treats the catalog as a reference manual and risks being overlooked).

• Established that the catalog is foundational, not a side resource.
• Future quality-guidance pages (motion, accessibility, etc.) follow the same Foundations placement pattern.
• Patterns and Anti-Patterns now sit in different sections, slightly less obvious as a pair, but more accurate to what they are.

Iconography was originally categorized as a Brand topic, placed next to Logo Usage and Imagery. But the content of Iconography is overwhelmingly foundational: icon sizing, labeling rules, accessibility, library curation, when to use which icon. It's not a brand-decision artifact; it's a use-the-system artifact.

Move `src/app/brand/iconography/` to `src/app/foundations/iconography/`, update navigation, update all cross-references.

Iconography sits in the same conceptual bucket as Color System (visual foundation), Spacing (system tokens), and Design Principles (quality guidance). Grouping it with Logo Usage and Imagery suggests brand-decision work, which is the wrong mental model for engineers and designers consuming it.

• Leave under Brand (rejected: wrong mental model).
• Duplicate in both sections (rejected: creates confusion and maintenance burden).
• Add a Foundations entry that links back to the existing Brand page (rejected: half-moves create lingering confusion).

• Brand section is now Typography, Logo Usage, Imagery.
• Foundations gained Iconography (and Motion, which landed in the same change).
• All four cross-references to /brand/iconography were updated.

Several content surfaces inherited the generic enterprise term 'employee' from upstream sources (ServiceNow standards, AI guardrails matrices, FAQ templates, policy templates). The internal corporate vocabulary at JM Family is 'associate'; using 'employee' reads as off-brand and externally framed, particularly in content the company itself authors.

Use 'associate' / 'associates' wherever the design system writes about, or for, JMF people. Applies to ServiceNow article standards, template scaffolds, AI guardrails examples, the AI writing rules, and any rendered prose in the site. 'Employee' remains acceptable only in a quoted or external context.

Terminology is a low-cost lever with high signal. Consumers (the Hub readers, Ask Hubert users, SN article authors) absorb the system's voice from the examples they see. Using the in-house term aligns the design system with the company's own language and avoids teaching new authors a vocabulary they will have to unlearn.

• Allow both interchangeably (rejected: produces inconsistency in templates and rendered examples; weakens the voice surface).
• Treat as a copy-edit preference, not a documented decision (rejected: drift will reintroduce 'employee' as new content lands).

• All occurrences of 'employee' in user-facing content replaced with 'associate' across ServiceNow standards, templates (FAQ, policy, public copies), AI writing guardrails, governance changelog, and the matching JSON sources.
• Future content additions must use 'associate'. Reviewers flag 'employee' in PRs unless quoting an external source.
• Voice & Tone and Grammar & Mechanics inherit this as the canonical term.

Em dashes had accumulated across pages, specs, and templates. Beyond stylistic taste, em dashes are widely read as an AI-generated tell, which undermines the design system's credibility as authored guidance. The editorial voice for teaching content already favors clarity over rhetorical flourish; em dashes were not earning their slot.

Remove em dashes from prose across the site, content templates, kit-templates, data feeds, and specs. Replace with colons (for definitions or list lead-ins), commas (for short connectors), or periods (for independent clauses). Keep em dashes only inside code blocks, JS/CSS/JSX comments, the Grammar & Mechanics teaching example, and as typographic 'no value' placeholders where text replacements would distort table layout.

The design system teaches by example. Prose seen as AI-generated weakens both the perceived authorship and the editorial voice we're asking content authors to adopt. Removing em dashes also forces sentences to commit to a clearer punctuation choice, which usually reads better. The cost is low (mechanical edits) and the consistency value is high.

• Allow em dashes sparingly with a guideline (rejected: under-specified guidance produced the original drift; a clean rule is easier to enforce and review).
• Replace em dashes only in user-facing pages, leave specs and docs untouched (rejected: agents and reviewers read those files; keeping the tell in internal docs models the wrong voice).
• Switch to en dashes (rejected: still feels stylized; doesn't address the underlying readability or AI-tell concerns).

• Em dashes removed from prose; remaining instances are in code comments, code blocks, or intentional teaching/placeholder use.
• Grammar & Mechanics is updated so the prescriptive rule matches what the site practices.
• Future PRs that introduce em dashes in prose are flagged in review.
• Reverses the prior 'apostrophes, em dashes, you-address are fine' allowance in the editorial-voice-for-teaching entry; that text was tightened during this audit.

After shipping Voice & Tone and Grammar & Mechanics, the remaining four Content placeholders were Terminology, Content Patterns, Inclusive Language, and AI Writing Guardrails. A scope review surfaced that three of those four would land as thin pages duplicating content already covered by Voice & Tone, Grammar & Mechanics, or the kit-templates content-standards primer. Adding pages for the sake of completing a section creates clicks-to-disappointment for visitors and maintenance debt for the solo builder.

Remove three entries from the Content navigation: Terminology, Inclusive Language, and Content Patterns. Keep AI Writing Guardrails as a placeholder because it is strategically distinct (AI-first charter) and warrants a dedicated page when scoped.

Terminology is covered by the canonical-acronyms and proper-nouns sections in Grammar & Mechanics, plus the plain-words list in Voice & Tone. Inclusive Language has settled, universal rules already shipping in kit-templates/content-standards.md; duplicating them on the site adds no instruction. Content Patterns (how to write notifications, emails, job postings) needs demand evidence before it earns a page; right now the same value is delivered by V&T's error and empty-state sections. AI Writing Guardrails stays because the strategic charter centers AI agents and the rules are non-obvious enough to merit their own treatment.

• Build all six pages as planned (rejected: three would be thin and duplicative).
• Build a single combined 'Other content rules' page (rejected: hides distinct content under a vague label; worse than dropping).
• Defer the decision and leave placeholders (rejected: every placeholder route is a small broken promise to visitors).

• Content section now has three entries: Voice & Tone (shipped), Grammar & Mechanics (shipped), AI Writing Guardrails (placeholder).
• The For Content Strategists role page updates its 'How to start' and 'Where to go next' lists to point at Grammar & Mechanics and the content-and-voice anti-patterns instead of the dropped pages.
• If a real domain-terminology problem surfaces at JMF, the answer is a one-paragraph addition to Grammar's acronyms section, not a new page.
• Inclusive Language remains canonical in kit-templates/content-standards.md and ships in the Agent Kit; no public-site teaching page exists.

The existing content layer (kit-templates/content-standards.md) covers product UI strings: voice, tone, plain language, button labels, errors, empty states. It does not cover content surfaces that have their own structure, retrieval behavior, and review workflow. ServiceNow knowledge articles are the first such surface: they are consumed by associates directly and by Ask Hubert, an AI-assisted enterprise search agent. Poor article structure causes Hubert to surface confusing fragments, and trust in the agent erodes. The fix is content quality, not better AI.

Add a top-level content/ folder for domain-specific content standards, with surface-specific files at the root and an author-facing templates subfolder. ServiceNow ships first with servicenow-article-standards.md, servicenow-quality-checklist.md, and five article templates. A new root AGENTS.md instructs repo-local agents on the SN article workflow; the existing kit-templates AGENTS.md is left untouched.

Domain content standards inherit voice, tone, plain language, accessibility, and inclusive language from the existing content and accessibility layers rather than duplicating them. Each surface has its own retrieval profile, structural constraints, and review cadence, which would either bloat content-standards.md or hide surface-specific guidance from the audience that needs it. A dedicated content/ folder keeps standards discoverable for the people who author for that surface, without polluting the Agent Kit shipped to product engineering teams.

• Expand kit-templates/content-standards.md to cover ServiceNow (rejected: mixes UI string rules with knowledge-article structure; bloats the kit for consumers who do not author SN content).
• Put SN standards in specs/ (rejected: specs are page specs for this site, not reference material for other content surfaces).
• Put SN standards in docs/ (rejected: docs/ is for repo-internal documentation like CHANGELOG and CONTRIBUTING, not for cross-team reference material).
• Bundle SN standards into the Agent Kit immediately (deferred: the kit ships to product engineering teams whose agents rarely author SN content; revisit if that changes).

• Content standards now live in two trees: kit-templates/ for product UI content shipped via the kit, and content/ for domain-specific surfaces consumed locally.
• A second AGENTS.md joins the existing kit-templates AGENTS.md. The two have separate audiences and should not be merged.
• Future content surfaces (Viva Engage, SharePoint, email) follow the SN pattern: standards file, parallel quality checklist, templates folder.
• The Decision Log surfaces this scope expansion publicly, alongside ADR-008 in docs/DECISIONS.md.

The initial anti-pattern entries were drafted in two tones: prescriptive-technical ('Use the semantic token, never hardcode the value') and editorial-conversational ('It's tempting to grab the hex value directly, but here's why that backfires'). Both worked; the question was which to standardize on.

Lean editorial. Keep rules and titles prescriptive and short. Write the *why*, the framing, and the consequences in plain, conversational language. Apostrophes and 'you' address are fine.

The educational mission means the audience is broader than engineers. Editorial voice lands for designers, PMs, and content folks while still working for technical readers. A dry reference manual undermines the teaching pillar; an overly chatty doc loses precision in the rule. The blend captures both.

• Pure technical / prescriptive voice (rejected: alienates non-engineers; the educational mission needs broader access).
• Pure conversational voice (rejected: loses precision in the rule itself and the code examples).

• Saved as a project-wide feedback preference; applies to anti-patterns, motion guidance, principles, content rules, future material.
• Tables, prop lists, and other strictly reference content stay terse; the rule applies to teaching content specifically.

The Motion page principles draw influence from Uxcel's '12 Principles of Animation' and NNGroup's 'Animation for UX'. Initial spec language tied our principles to those sources ('a narrowed and recontextualized subset of these twelve'). Question: keep the per-principle attribution, or write them as our own?

Write the principles as our own. Use punchier renames ('Ease, don't lurch' instead of 'Easing'). List source articles in Further Reading only, with a closing note that the principles 'stand on their own: they are written for our context and are not numbered against any external source.'

External articles move and renumber. If Uxcel changes their list from 12 to 10 or renames a principle, our citations break and our list looks out of sync. Punchier names also land better with our audience. Sources still get acknowledgment as inspiration, just not as load-bearing structure.

• Direct quotes with full attribution (rejected: couples our content to external sources we don't control).
• Use canonical names like 'Easing' and 'Offset & Overlapping Action' (rejected: less memorable, more textbook-feeling).
• Drop the inspiration entirely and write from scratch (rejected: the influence is real; attribution is honest).

• Motion page has 6 self-standing principles.
• Sources credited in Further Reading section only.
• Sets a pattern for future content drawing from external sources: inspire from, don't couple to.

The pre-hydration theme script was honoring prefers-color-scheme on first load, so any visitor whose OS was in dark mode landed in dark before they had a chance to choose. Preview feedback (2026-05-26) was that this read as unpredictable: the design system is showcased to stakeholders in light, demoed in light, and the canonical surface is the light theme. Auto-switching at the OS level made the first impression inconsistent with how the system is talked about.

Remove the prefers-color-scheme branch from the pre-hydration theme script. First-load theme is always light. Dark mode is reached only by clicking the toggle, and the choice is persisted in localStorage under ds-theme. The persisted choice still wins on subsequent visits.

The design system is a teaching surface, not an end-user product. Predictable defaults beat user-system-preference inference for a stakeholder-facing site that is referenced, screenshotted, and demoed in light. Dark mode remains a first-class option (it's still fully designed, fully toggleable, and persists once chosen), but it is no longer the default for a population of visitors who never asked for it.

• Keep prefers-color-scheme honor (rejected: produced the inconsistency that triggered this decision; dark-mode OS users landed in dark unexpectedly).
• Dark as the unconditional default (rejected: conflicts with how the system is shown and referenced internally; the canonical surface is light).
• First-visit prompt asking the user to pick (rejected: friction with no clear benefit; the toggle is already discoverable in the shell).

• Users on dark-mode OSes see light first; they can toggle and the choice sticks.
• Screenshots, demos, and external reference materials match what new visitors see, with fewer 'wait, mine looks different' moments.
• Dark theme still gets full contrast and token coverage; nothing about its design budget changes.
• If dark adoption becomes the dominant pattern internally, this decision is worth revisiting.

The brand secondaries were documented in the Color page reference grid but had no token presence: orange was missing entirely from the global palette, and the existing color.green / color.yellow tokens carried Tailwind values used by the feedback (success / warning) system, not the warmer / softer JMF brand spec. As a result, the brand secondaries existed as labels on a page but could not be applied as accents anywhere in the app.

Add a new global color.brand group (orange, yellow, green) at the JMF brand-spec values with derived 50 / 500 / 700 shades. Map these to semantic accent tokens (accent.{name}.{bg,fg,text}) for both light and dark themes. Extend PageHero with an accent prop ('orange' | 'yellow' | 'green') that swaps the eyebrow color, icon badge gradient, and hero panel gradient. Apply: orange to Content pages (Voice & Tone, Grammar, AI Writing Guardrails), green to Resources pages (Asset Library), yellow to AI Toolkit pages (Agent Kit).

Feedback colors (success, warning, error, info) are functional signals tuned for accessibility contrast; using them as accents would weaken the system's status vocabulary. Brand secondaries are visual identity; using them as accents differentiates sections without diluting the primary brand teal that ties the system together. Tokenizing them separately preserves both vocabularies. The mapping (orange = Content, green = Resources, yellow = AI Toolkit) leaves the strategic teal sections (Foundations, Tokens, Components, Brand) at the default, so primary identity stays loud.

• Replace the existing color.green and color.yellow with brand values (rejected: would break the feedback system that depends on Tailwind shades for tuned contrast).
• Skip tokenization and hardcode the brand hex values per page (rejected: same drift problem the rest of the system exists to prevent).
• Apply accents to every section, including Foundations / Tokens / Components (rejected: dilutes the primary brand identity; reserves accents for sections that benefit from distinction).

• Three new global color groups (color.brand.orange, color.brand.yellow, color.brand.green) and a new accent semantic group land in the token system.
• PageHero gains an optional accent prop; default behavior unchanged for the rest of the system.
• Content / Resources / AI Toolkit pages now have visually distinct heroes; visitors can identify which section they're in at a glance.
• Future sections that want distinction (for example a hypothetical Workflow or Patterns accent) extend the same accent type union and pass the prop.
• Open question: should the catalog Medium severity badge use brand yellow instead of the Tailwind feedback yellow to better separate visual identity from system signal? Tracked as a follow-up.

The first version of the Motion page had per-row Play demos for each duration and easing token. In practice, the differences were subtle and hard to perceive in isolation. 100ms vs 200ms looks nearly identical to most viewers, and easing curves at 200ms are too fast to see the shape.

Add a Race button per table that fires all rows simultaneously via a window event. Keep per-row Play for focused exploration. Switch easing demos specifically to use `motion.duration.slower` so the curves play over enough time to perceive their shape.

Differentiation is a comparative skill: you see the difference between 100ms and 500ms when they race side by side, not when you play them three minutes apart. Easing curves are about the shape of velocity over time; shape needs time to register on the retina, and 200ms is below that threshold for most curves.

• Keep per-row only (rejected: fails the teaching goal of the page).
• Replace with static side-by-side visualizations (rejected: less informative than a live race; loses the felt quality of motion).
• Lengthen all demos to 500ms uniformly (rejected: would distort the duration demos, which are specifically about feeling the time difference).

• Token tables become teaching tools, not just reference lookups.
• New components shipped: `RaceButton`, `useReducedMotion` hook (shared by PlayDemo + RaceButton).
• Race buttons disable themselves under `prefers-reduced-motion: reduce`, with the same 'Reduced motion' label as individual Play buttons.

/governance/review documented an internal review process for an audience of one (Sergio reviews everything). /governance/versioning published a philosophy (additive by default, deprecation runway, three change types) for a discipline the system hadn't actually exercised yet (no v1 to v2, no real deprecation). Both pages took up sidebar space without serving the consumer; meanwhile the genuinely useful pieces (what tooling catches before review, when to re-download the Agent Kit, the source-of-truth framing) were buried inside them.

Remove both pages from /governance/. Move 'What the tooling catches' into Contribute under a #tooling anchor. Move the Agent Kit re-download cadence to the Agent Kit page (which already had related copy). Add a 'How changes ship' section at the top of Changelog that captures the additive-by-default framing and the agent-kit refresh note.

The system's audience is consumers without repo access; an internal-process page for a single maintainer is the wrong shape for them. The versioning philosophy is worth restoring once the system has a real breaking change to defend. Until then, the framework is paperwork ahead of practice. Salvaging the genuinely useful parts preserves the value without keeping pages that imply a larger governance apparatus than actually exists.

• Keep both pages as-is (rejected: they read as aspirational and clutter the sidebar).
• Consolidate both into Contribute as subsections (rejected for the philosophical content; accepted for the tooling list).

• Governance sidebar slims from 7 to 5 items.
• Direct visits to /governance/review and /governance/versioning return 404, acceptable since both were stubs with little external reference.
• Spec docs (specs/APPLICATION_SHELL.md, specs/ASSET_LIBRARY.md) still describe the old shape; flagged for a separate spec-cleanup pass.