This repository contains:

• exported variables from our Rider Design System Figma library, defining standard colors, sizes, and more
• scripts to transform those variables into formats usable by applications
• Elixir function components, LiveComponents, and default styles provided via compiled CSS, JS, and Tailwind v3 configuration preset
• a web application documenting these styled components in an interactive Storybook-like experience

To launch the Storybook and demo all of the mbta_metro components:

%> npm install --prefix assets
%> mix deps.get
%> mix assets.build
%> mix phx.server

Now you can visit http://localhost:4000/storybook from your browser.

Installing MBTA Metro in Your Phoenix Application

Add this to your mix.exs:

def deps do
  [
    {:mbta_metro, ">= 0.0.0"}
  ]
end

Import mbta_metro's styles in your assets/css/app.css:

@import "../../deps/mbta_metro/priv/dist/metro.css";

If you want to use mbta_metro's LiveComponents, you'll need to add its hooks in your assets/js/app.js:

import { Hooks } from "../../../mbta_metro/priv/dist/metro";

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: {
    ...Hooks
  }
})

If you want to include hooks individually, you can do so:

import {Map} from "../../../mbta_metro/priv/dist/metro";

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: {
    Map
  }
})

Optional: Configure Tailwind

If using Tailwind, you can use the provided tokens.js in your Tailwind configuration, as the tokens are structured as a Tailwind theme. Using this will give you access to utility classes like p-sm, font-heading or bg-red-line that are tailored to the Rider Design System. You must add references to the Metro dependency files in your content section.

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    // ...your other content
    "../deps/mbta_metro/lib/mbta_metro/components/*.ex",
    "../deps/mbta_metro/lib/mbta_metro/live/*.ex",
  ],
  /* whatever other properties */
  presets: [require("./../deps/mbta_metro/priv/dist/tokens")],
};

Custom Icons

Along with all of the free Font Awesome icons, you can add custom icons by pointing to any directory you like. E.g.,

config :mbta_metro, custom_icons: "#{File.cwd!()}/priv/static/icons/your-directory/your-icon.svg"

SVGs in the above directory will be turned into icons and can be used as follows:

<.icon type="your-directory" name="your-icon" class="..." />

LiveComponents

Some components, like the Map, take further configuration.

Map

The map components uses maplibre-gl so you must pass in config with a valid style spec.

You can use an external style source.

@api_key = Application.compile_env!("MBTA_METRO_MAP_API_KEY")

config :mbta_metro, :map, %{
  style: "https://tiles.stadiamaps.com/styles/alidade_smooth.json?api_key=#{@api_key}"
}

If you do use an external source you'll have to make sure it is defined in your CSP (assuming you have one):

[
  "child-src blob: ;",
  "connect-src *.stadiamaps.com",
  "worker-src blob: ;"
]

Or, you can define your own style.

config :mbta_metro, :map, config: %{
  center: [-71.0589, 42.3601],
  style: %{
    "version" => 8,
    "sources" => %{...},
    "layers" => %{...}
  },
  zoom: 15
}

Production usage

WIP, so long as you're using the files from deps/mbta_metro/priv/dist it should work.

There are also icons and fonts, which can be added to your application's /priv/static directory with the mix task mix mbta_metro.export_assets.

Contributing

We welcome contributions! To add a local version of mbta_metro to your application, use the path option:

{:mbta_metro, path: "../mbta_metro", app: false}

Building tokens

Variables have to be exported out of Figma manually. This is at assets/figma-tokens.zip, unzipped to assets/figma-tokens/. Building the tokens is as simple as running mix tokens.build -- StyleDictionary will complain about some things, but it ultimately works.

The workhorse script, a Style Dictionary configuration located at assets/process-figma-tokens.js, may need adjusting if the structure of the Figma variables changes.

It generates a few variables.*.css files in assets/css/ and a single JavaScript file at assets/js/tokens.js. This JavaScript file basically matches the structure of a Tailwind theme.

Compiling assets

After making edits to mbta_metro, you will have to run the mix assets.build script to regenerate the compiled CSS and JS. This runs the Esbuild and Tailwind CLI commands to process the assets and produce the following files in priv/dist/:

• metro.css - bundled CSS for all components, including any component dependencies
• metro.js - bundled JS for all components, including any component dependencies
• tailwind-preset.js - a Tailwind configuration containing a theme tailored to the MBTA Rider Design System (including bundled plugins)

Publishing

You can publish a new release with a single script:

%> git checkout main
%> git pull origin main
%> ./release
Please enter a release level [patch | minor | major]: patch
...
%> git push origin main

Note this rebuilds the tokens, recompiles the assets, and bumps the application version automatically.