Pathway

Design system for Ministry Brands Amplify. Tokens + components + specifications, all versioned in one place, with Storybook deployed from main.

Using the tokens

The Pathway token library is published to npm and updated automatically on every token sync.

npm install @helloimjolopez-pathway/pathway-tokens

// CSS custom properties — import once in your app entry point
import "@helloimjolopez-pathway/pathway-tokens/css";

// JS token object
import tokens from "@helloimjolopez-pathway/pathway-tokens";

// Raw DTCG JSON (for tooling)
import tokenJson from "@helloimjolopez-pathway/pathway-tokens/json";

Without a bundler — link the CSS directly:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/tokens.css" />

Once loaded, use the custom properties anywhere:

.my-component {
  background: var(--semantic-color-light-mode-fill-static-brand-base);
  color:      var(--semantic-color-light-mode-text-static-primary-inverse);
}

Full token reference: Storybook → Tokens · Token architecture · Agent brief

Layout

pathway-ds/
├── docs/                        Cross-component design-system docs
├── components/                  One folder per component
│   ├── sidenav/
│   │   ├── sidenav.html         Live React demo + annotated spec panel
│   │   ├── sidenav-figmamake.html  AI-codegen-friendly demo (auto-synced)
│   │   └── sidenav-spec.md      Authoritative specification
│   └── spinner/
│       ├── spinner.html
│       └── spinner-spec.md
├── tokens/                      Source-of-truth token JSON
│   ├── figma-export/            Raw Figma export (sync target)
│   └── pathway-design-tokens.json   W3C DTCG format
├── src/
│   ├── tokens/                  Built output (tokens.css + tokens.js)
│   └── stories/                 Storybook sources
│       ├── Primitives/          Token primitives (Color, Typography, Units)
│       ├── Semantics/           Semantic tokens (light/dark, layout, typography)
│       └── Library/             Component stories (one folder per component)
├── .storybook/
├── .github/workflows/           Token sync · component sync · Storybook deploy
├── scripts/                     Token sync/audit/fix + component build scripts
└── storybook/                   Built Storybook output (deployed by CI)

Governance — where things live

| To change… | Where | |---|---| | Published token package | @helloimjolopez-pathway/pathway-tokens | | Token values | tokens/pathway-design-tokens.json (source-of-truth, synced from Figma) | | Built CSS consumed by Storybook | src/tokens/tokens.css (auto-regenerated by Style Dictionary) | | Component geometry, tokens, accessibility rules | components/<name>/<name>-spec.md | | Component reference implementation | components/<name>/<name>.html | | How a component appears in Storybook | src/stories/Library/<Name>/ | | Storybook chrome / addons | .storybook/main.js · .storybook/preview.js | | CI behaviour | .github/workflows/ |

CI

Three workflows in .github/workflows/:

1. sync-tokens.yml — fires when tokens/figma-export/** changes. Normalises the Figma export into the W3C DTCG JSON and commits tokens/pathway-design-tokens.json.
2. sync-component.yml — fires when components/sidenav/sidenav.html changes. Regenerates the sidenav-figmamake.html variant and commits it.
3. deploy-storybook.yml — fires when tokens/, src/, .storybook/, components/, docs/, or style-dictionary.config.js changes. Rebuilds Style Dictionary + Storybook and commits the built site to /storybook/ on main. GitHub Pages serves that folder.

Source of truth is always the repo on main; Storybook is a downstream artifact.

Typography (brand fonts)

Pathway uses Red Hat Text (all UI text) and Red Hat Display (headings H1–H3 only). Both are open-source Google Fonts.

Load via CDN (web/prototypes):

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Red+Hat+Display:wght@600&family=Red+Hat+Text:wght@400;500;600;700&display=swap" rel="stylesheet" />

Download font files (for Claude Design, Figma, or offline tools):

• Red Hat Text: https://fonts.google.com/specimen/Red+Hat+Text → click Download family
• Red Hat Display: https://fonts.google.com/specimen/Red+Hat+Display → click Download family

Licensed under the SIL Open Font License. Free for any use.

Component-to-token map

tokens/component-token-map.json maps every component element to its CSS variable. Use this file to answer "which token does X use?" without reading specs.

Known token gaps

| Gap | Fix needed | |---|---| | Font-size tokens are unitless numbers | Use calc(var(--...-fontsize) * 1px) in CSS | | No Red Hat Display token | Add family-display: Red Hat Display in Figma Variables, re-export |