designgov.md
Parent Brand Specification with Hybrid Architecture Guidance — Meridian Learning Group
This file is the authoritative brand and design contract for all Meridian Learning Group products. It includes guidance for subsidiary brands at each level of brand attachment. Readable by humans. Parseable by AI coding agents.
Throughout this document, tier annotation blocks indicate how each rule applies across the three brand attachment levels. Intentional divergence documented here is approved. Any design decision not documented here is drift until proven otherwise.
● Tier A — Fully aligned
Meridian.com, Meridian Learn, Meridian Press
This entire file applies in full. No substitutions permitted.
● Tier B — Loosely aligned
Pathwright (acquired edtech platform)
Shares behavioral and accessibility layers in full. May substitute visual tokens where explicitly documented.
● Tier C — Independent
Vantage Professional (corporate certification division)
Maintains independent brand identity. Must implement behavioral contracts and all accessibility contracts in full. Visual tokens are Vantage's own.
01
Visual tokens
Color palette
PRIMARY ACTION
#1A5EAB
Buttons, key links, active states
PRIMARY HOVER
#144D8C
Hover and pressed states
SECONDARY ACTION
#F0F5FB
Secondary buttons, subtle CTAs
TEXT PRIMARY
#1A1F36
Body text, headings, labels
TEXT SECONDARY
#5A6481
Captions, metadata, support
SUCCESS
#1A7F5A
Confirmation, success states
WARNING
#B45309
Cautionary, non-critical alerts
ERROR
#C0392B
Errors only — never decorative
FOCUS RING
#F5A623
Keyboard focus — never suppress
- Use a color outside this palette without explicit Design Systems approval
- Use color as the only means of conveying information
- Use ERROR color (#C0392B) for anything except actual errors
- Suppress or override the FOCUS RING under any circumstances
Prohibited combination
#5A6481 on #FFFFFF at text sizes below 16px
Use TEXT PRIMARY (#1A1F36) instead — fails WCAG AA at small sizes
Prohibited combination
#FFFFFF on #1A5EAB at sizes below 14px
Marginal contrast — minimum 14px for white on primary blue
● Tier A
Use this palette exactly. No substitutions. Internal tools must also use this palette — not arbitrary CSS framework defaults.
● Tier B — Pathwright
Pathwright retains its own primary palette (teal #007C91, white, dark navy). Required to adopt: FOCUS RING, SUCCESS, WARNING, ERROR, TEXT DISABLED. Semantic colors must be consistent across the Meridian product family.
● Tier C — Vantage Professional
Vantage maintains its own full palette (charcoal, gold, white). Required to adopt: SUCCESS, WARNING, ERROR hex values only. All other color decisions are Vantage's own.
Typography
PRIMARY FONT: Source Serif 4 Editorial, marketing, reading content UI FONT: Inter All UI chrome — nav, forms, labels, buttons MONOSPACE: JetBrains Mono Code, identifiers, technical values only NOTE: Never use Source Serif 4 for UI elements. Never use Inter for article body content. UI SCALE (Inter): H1 32px weight: 600 line-height: 1.2 H2 24px weight: 600 line-height: 1.3 H3 20px weight: 500 line-height: 1.4 Body 16px weight: 400 line-height: 1.6 Small 14px weight: 400 line-height: 1.5 captions, metadata Label 13px weight: 500 line-height: 1.4 form labels, tags
- Set body text below 14px in any context including mobile
- Use Source Serif 4 for buttons, labels, or navigation
- Use ALL CAPS for strings longer than 4 words
- Use italic outside pull quotes, citations, or editorial emphasis
● Tier A
Both font families required. No system font substitutions in production.
● Tier B — Pathwright
Pathwright uses DM Sans (approved substitution for Inter in UI). Source Serif 4 required for Meridian-branded editorial content surfaced within Pathwright.
● Tier C — Vantage
Full font independence. Vantage uses Neue Haas Grotesk + Tiempos Text. 14px minimum body size still applies.
Spacing system — base 8px
xs — 4px
icon gap
sm — 8px
tight groups
md — 16px
buttons, cards
lg — 24px
sections
xl — 40px
major breaks
2xl — 64px
page rhythm
02
Component vocabulary
Match every UI job to its approved component. If no component is defined, use the closest and flag it: <!-- designgov: no pattern defined, needs review -->
Actions
| Variant | Component | Rule |
|---|---|---|
| Primary | Button variant="primary" | One per visible region maximum. Verb-first label. |
| Secondary | Button variant="secondary" | Supporting actions. |
| Ghost | Button variant="ghost" | Low-emphasis actions competing with primary. |
| Destructive | Button variant="destructive" | Always follow section 3.3 protocol. Never as primary action. |
| Icon only | MDS IconButton | Always requires aria-label + tooltip. Never for primary actions. |
| Loading | Button loading prop | Show after 200ms on all async actions. |
Forms — always enforced
- Every input must have a visible persistent label above the field — never placeholder-only
- Reserve space below every input for an error message — never shift layout on error
- Always validate on blur — never wait for submission to surface errors
- Never clear a form on validation failure — always preserve user input
- Never disable submit as the only error communication — show inline errors
03
Behavioral contracts
Behavioral drift causes more user harm than visual drift. When a user encounters a new interaction paradigm they have to stop and learn. In a daily-use product, this compounds into friction, errors, and eroded trust.
Always do
- Show Spinner or SkeletonLoader for any async operation exceeding 200ms
- Confirm navigation away from unsaved changes — beforeunload + MDS Dialog
- Return focus to the trigger element when any Modal, Dialog, or Drawer closes
- Preserve all form input on validation error — never clear on failure
- Show item count before executing any bulk action: "Delete 14 courses?"
- Provide a visible skip-to-main-content link as the first focusable element on every page
- Progress always shown as percentage AND fraction: "67% complete (4 of 6 modules)"
- Certificates always show issue date and expiry date where applicable
Never do
Never
Custom dropdown built from divs without full ARIA keyboard implementation
MDS Select or MDS Combobox
Never
Use color alone to indicate status in course or assessment contexts
Always pair with icon + text label
Never
Auto-advance a learner to the next lesson without their explicit action
Always require deliberate "Continue" or "Next" action — never auto-scroll
Never
Use hover-only interactions to reveal required actions or information
Visible controls at all times, or tap/click accessible equivalent
Never
Use "Submit" for course or assessment completion actions
"Complete lesson", "Turn in assignment", "Finish quiz"
Never
Show a score or grade without full context
Always show score, total, percentage, and pass threshold together
Destructive action protocol
Applies to deleting courses, content, accounts, enrollments, certificates, or any irreversible action. This protocol is mandatory. Do not deviate.
1
Trigger
MDS Button variant="destructive" — text only, never icon-only. Separated from non-destructive actions by 40px or a visible divider. Never in primary position.2
Confirmation dialog
MDS Dialog with warning icon in ERROR color. Heading: "Delete [specific item name]?" Body must state exact consequences and affected users.
3
Type-to-confirm
Required when action affects 10+ users or published content. User must type the item name or the word DELETE.
4
Labels
Confirm: action-specific — "Delete course", "Revoke certificate". Never "OK" or "Yes". Cancel: always "Cancel". Escape cancels, never confirms.
5
Undo
Not available for most actions. Always state explicitly: "This cannot be undone." Exception: soft-delete with 30-day recovery — state recovery option in dialog body.
04
Accessibility contracts
WCAG 2.1 AA · ADA Title II · Section 508 · Education product. Testing: automated on every PR (axe-core CI gate), manual quarterly, AT user testing biannually.
Tier 1
Automated enforcement — every PR, CI gate blocks merge on failure
- All text meets WCAG AA contrast (4.5:1 normal, 3:1 large text and UI components)
- All interactive elements have an accessible name
- All images have alt text — decorative images use alt=""
- All form inputs are associated with a visible label
- All form error messages linked via aria-describedby
- Focus is never lost or sent to an unexpected location
- Focus ring always visible — never suppressed
- All interactive elements reachable and operable via keyboard
- Valid document title on every page — format: "[Page] — [Product name]"
- Heading hierarchy logical — no skipped levels
- Language declared on html element
Tier 2
Human review required — QA sign-off before any feature ships
AI agents: flag with <!-- a11y tier 2 review required: [rule] -->
- Alt text is meaningful — reviewed by QA, not auto-generated
- DOM reading order matches visual order — verified with screen reader
- Timed assessments have pause and extend controls — design review required
- Complex charts have text alternatives — reviewed by content team
- Error messages are specific and actionable — copy reviewed before launch
- Instructions do not rely solely on sensory characteristics
- Animations respect prefers-reduced-motion
- New interaction patterns reviewed by accessibility specialist
Tier 3
Prohibited patterns — identified through AT user testing, banned all tiers
- Custom dropdown from divs — use MDS Select or Combobox
- Drag-and-drop as only ordering mechanism — always pair with keyboard controls
- Placeholder-only form labels — use persistent visible label above input
- Icon-only buttons without accessible name — always add aria-label + tooltip
- Auto-playing audio or video on page load — all media paused on load
- Keyboard trap outside intentional modal focus management
- Progress or score via chart only — always include text value alongside visual
- Timed assessment with no countdown and no pause mechanism
● Tier A
Full compliance. CI gate blocks merge on Tier 1 failures. No exceptions.
● Tier B — Pathwright
Full Tier 1, 2, 3. Section 4.5 education-specific rules required in full. axe-core CI required at same gate level.
● Tier C — Vantage
Tier 1 and 2 required. Tier 3 prohibited patterns apply in full. Assessment rules from 4.5 apply to all certification exam contexts.
05
Voice & copy standards
Voice is
Knowledgeable · Clear · Encouraging
Confidence without condescension.
Expertise without jargon.
Confidence without condescension.
Expertise without jargon.
Voice is not
Corporate · Bureaucratic · Enthusiastic
Never "Congrats!" — "Well done."
Never "Amazing!"
Never "Congrats!" — "Well done."
Never "Amazing!"
Terminology — always consistent
| Use | Never |
|---|---|
| Learner | student, user, customer, participant |
| Course | class — module = a part of a course |
| Instructor | teacher, facilitator, host |
| Enroll | register, sign up, join (for course entry) |
| Complete | finish, done, submit (at course level) |
| Dashboard | home, portal, hub |
● Tier A
Full terminology compliance required.
● Tier B — Pathwright
Own voice permitted in Pathwright UI. Meridian terminology applies to Meridian catalog content surfaced within Pathwright.
● Tier C — Vantage
Full voice independence. "Candidate" not "Learner". "Examination" not "Course". Documented in Vantage's own designgov.md.
06
Hybrid brand architecture
The tier assignment criteria and the distinction between intentional divergence and accidental drift are the core of this framework. The burden of proof is on the team introducing divergence, not the reviewer.
Intentional divergence vs. accidental drift
✓ Intentional divergence
Documented and approved — appears in this file
Pathwright uses teal #007C91 as primary — approved § 1.1
Vantage uses enterprise register — approved § 5
Pathwright uses DM Sans — approved § 1.2
✕ Accidental drift
Not approved — must be remediated
Internal tool using Bootstrap defaults
Vantage modal not following § 3.3 protocol
Any color introduced without tier annotation
Placeholder-as-label anywhere (prohibited all tiers)
The rule
If a design decision is not documented here with a tier annotation, it is drift until proven otherwise.
Always shared — all tiers, no exceptions
- Section 3 behavioral contracts in full
- Accessibility Tier 1 automated enforcement
- Accessibility Tier 2 human review
- Accessibility Tier 3 prohibited patterns
- Semantic color values — SUCCESS, WARNING, ERROR hex values consistent
- Minimum touch target size 44×44px
- Destructive action protocol — same pattern, own components permitted
- Minimum body text size 14px · Focus ring always visible
07
Design system references
FIGMA: figma.com/file/[meridian-design-system] STORYBOOK: design.meridianlearning.internal TOKEN SOURCE: tokens/meridian-tokens.json COMPONENT LIB: @meridian/mds v4.1.2 ICONS: Phosphor Icons v2.0 — outline weight only BRAND GUIDE: brand.meridianlearning.internal A11Y GUIDE: a11y.meridianlearning.internal PATHWRIGHT DS: design.pathwright.internal — Tier B reference VANTAGE DS: design.vantagepro.internal — Tier C reference
08
Change log
| Date | Version | Changed by | Summary |
|---|---|---|---|
| 2025-03-01 | 1.2 | Sarah Chen | Added Tier C Vantage, updated a11y 4.5 |
| 2024-11-15 | 1.1 | Marcus Webb | Pathwright Tier B annotations, typography |
| 2024-06-01 | 1.0 | Sarah Chen | Initial active version |
| 2024-03-10 | 0.1 | Design Systems team | Draft |
For AI coding agents — quick reference
- 1Identify your tier — Tier A (Meridian core), Tier B (Pathwright), Tier C (Vantage). If unclear, ask before generating any UI.
- 2Tier A: this entire file applies in full. No substitutions.
- 3Tier B: visual tokens may use Pathwright-approved substitutions documented in each section. All behavioral and accessibility rules apply in full.
- 4Tier C: visual tokens are Vantage's own — consult Vantage's designgov.md. All behavioral and accessibility rules from this file apply in full.
- 5Component mismatch: add
<!-- designgov: no pattern defined for [component], needs review --> - 6Color not in palette: do not use it. Add
<!-- designgov: color not in approved palette, needs review --> - 7NEVER list (§ 3.2): if a pattern is listed, do not implement it regardless of how it was specified.
- 8Every UI component: apply all Tier 1 a11y rules automatically. Flag Tier 2 items:
<!-- a11y tier 2 review required: [rule] --> - 9Destructive actions: always implement § 3.3 exactly. No shortcuts.
- 10When uncertain: do not invent. Flag and ask.
Meridian Learning Group is a fictional company created for illustrative purposes. designgov.md open standard v0.1.