Midwest Component Library

Midwest Component Library is an implementation of the Midwest Design System using ViewComponent.

This library is under active development. Breaking changes are likely until stable release.

Usage

Render Midwest ViewComponents:

= midwest_card(title: "Title") do
  %p Card example

Dependencies

• Stimulus

Installation

Add to Gemfile:

gem "midwest", git: "[email protected]:unabridged/midwest.git", branch: "main"

Run installer:

bin/rails midwest:install

Development

To get started:

1. Run: bundle install
2. Run: yarn install
3. Run: git config core.hooksPath .githooks to enable the pre-commit lint hook
4. Run: bin/dev

It will open demo app with component previews on localhost:4000. You can change components and they will be updated on page reload. Component previews located in demo/app/previews.

Running tests

Run the full suite against the current Ruby version:

bin/test

Run the complete matrix — every appraisal × every supported Ruby version:

bin/test --all

Target a specific Rails or Bridgetown version:

bin/test --rails 8
bin/test --bridgetown v2
bin/test --rails 7,8

Run jobs sequentially instead of in parallel:

bin/test --no-parallel

Target specific files, directories, or glob patterns:

bin/test test/integration/navigation_test.rb         # single file
bin/test test/components/                            # all tests in a directory
bin/test "test/components/midwest/popover*"          # glob pattern
bin/test --rails 8 test/integration/                 # scoped appraisal + directory
bin/test --all test/integration/navigation_test.rb   # single file across full Ruby matrix

Compatibility matrix

The gem uses Appraisal to test against multiple Rails and Bridgetown versions. Ruby 3.1 and 3.2 are end-of-life and no longer tested.

| Appraisal | Target | Ruby | |---|---|---| | rails-7 | Rails ~> 7.1 | 3.3, 3.4 | | rails-8 | Rails ~> 8.0 | 3.3, 3.4 | | bridgetown-v1 | Bridgetown ~> 1.0 | 3.4 | | bridgetown-v2 | Bridgetown ~> 2.0 | 3.4 |

Ruby versions are installed and managed via asdf. To install any missing versions from the matrix:

bin/setup-rubies

Generating new components

bin/rails midwest:generate:component YourComponent

The syntax follows ViewComponent's generator.

MCP Server

Midwest ships an MCP server that gives AI agents live access to the component API. To connect, add to .mcp.json:

{
  "mcpServers": {
    "midwest": {
      "command": "bundle",
      "args": ["exec", "midwest_mcp"]
    }
  }
}

The server exposes 8 tools: list_components, get_component_api, search_components, get_component_examples, get_helper_methods, get_form_builder_info, get_component_relationships, and validate_component_usage.

Component Guidance

The MCP server includes a guidance system that helps agents avoid common composition mistakes. Guidance is stored in lib/midwest/mcp/data/component_guidance.yml and surfaced through MCP tools automatically.

Two data sources feed into guidance:

• Auto-detected: Template scanning discovers which components internally render other components (e.g., StatComponent renders a CardComponent). This powers redundant nesting warnings.
• Curated: Anti-patterns and best practices added to the YAML file from real agent mistakes observed in the field.

Use bin/guidance to manage guidance data:

bin/guidance              # List components with guidance and auto-detected internal renders
bin/guidance show stat    # Show full guidance for a component
bin/guidance add          # Describe a pattern in plain text; Claude formats and appends it
bin/guidance scan         # Display the internally-renders graph for all components
bin/guidance check        # Validate YAML keys against the component index

The add command opens your $EDITOR for you to describe an anti-pattern or best practice in plain English. When you save and close, the Claude CLI processes your description into properly formatted YAML and appends it to the guidance file. This is the fastest way to capture a mistake you spotted an agent making in the field.

You can also edit lib/midwest/mcp/data/component_guidance.yml directly:

stat_component:
  anti_patterns:
    - title: "Wrapping stat in a card"
      description: "StatComponent already renders a CardComponent internally."
      bad: |
        <%= midwest_card do %>
          <%= midwest_stat value: "1,234", label: "Users" %>
        <% end %>
      good: |
        <%= midwest_stat value: "1,234", label: "Users" %>
  best_practices:
    - title: "Group stats in a grid"
      description: "Use midwest_grid to lay out multiple stats."
      example: |
        <%= midwest_grid columns: 3 do %>
          <%= midwest_stat value: "1,234", label: "Users" %>
          <%= midwest_stat value: "567", label: "Orders" %>
        <% end %>

Run bin/guidance check after editing to verify all component keys are valid.

Deploying your application

In order to deploy your application the deploy server will need access to the private repo. One way to accomplish that is to add the deploy key on this repo to the deploy server. You should be able to create the key from the values in the Shared 1Password vault entry "GitHub - Midwest"

Staging environment

A staging environment is hosted via Dokku. To deploy to it, add the remote once:

git remote add staging [email protected]:midwest

Then deploy by pushing to the remote:

git push staging main

Releases

The library follows semantic versioning. To draft a new release run bin/release with a new version number:

bin/release VERSION

This script will update the version in the gem and push it to GitHub and Rubygems automatically.

To release a new version of the npm package, update package.json with the new version number and run:

npm run release

After that make sure to commit changes in package.json.

License

The gem is available as open source under the terms of the MIT License.