Add curated Reference Apps library

_data/reference_apps.yml

@@ -0,0 +1,103 @@
+# Reference Apps — a curated library of exemplary open-source Rails apps.
+#
+# The bar for inclusion is intentionally high. An app belongs here only if it
+# is worth reading to learn how a real, production-quality Rails app is built:
+#
+#   * Open source under a permissive license, with a public repository.
+#   * Idiomatic, modern Rails — a strong example of the conventions and tools
+#     the framework encourages today.
+#   * Actively maintained, or a complete and self-contained reference.
+#   * Substantial enough to teach something, but readable end to end.
+#
+# To propose an app, open a pull request adding an entry below. Keep blurbs to
+# a single sentence and limit tags to the 2-3 patterns the app best
+# demonstrates. Entries render in the order listed here.
+
+apps:
+  - name: Campfire
+    by: 37signals
+    blurb: A complete, real-time group chat app — a compact masterclass in server-rendered Hotwire and lean, dependency-light Rails.
+    tags: [Hotwire, Turbo Streams, Action Cable]
+    repo: https://github.com/basecamp/once-campfire
+    screenshot: /assets/images/reference-apps/campfire.webp
+
+  - name: Writebook
+    by: 37signals
+    blurb: A self-hosted platform for publishing books on the web, showcasing clean model design, Active Storage, and rich text editing.
+    tags: [Active Storage, Action Text, Auth]
+    repo: https://github.com/basecamp/writebook
+    screenshot: /assets/images/reference-apps/writebook.webp
+
+  - name: Fizzy
+    by: 37signals
+    blurb: A Kanban board reimagined — drag-and-drop boards built with modern Hotwire patterns and crisp, RESTful controllers.
+    tags: [Hotwire, Stimulus, RESTful design]
+    repo: https://github.com/basecamp/fizzy
+    screenshot: /assets/images/reference-apps/fizzy.webp
+
+  # --- Placeholder/mock entries (remove before launch) -----------------------
+  # These are fictional apps with generated screenshots, used to fill out the
+  # grid while the real library is curated. Replace or delete each one.
+
+  - name: Beacon
+    by: Lighthouse Labs
+    blurb: A self-hosted help desk for small teams — shared inbox, ticketing, and canned replies, all server-rendered.
+    tags: [Action Mailbox, Hotwire, PostgreSQL]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-beacon.png
+
+  - name: Cadence
+    by: Tempo
+    blurb: A focused sprint board for product teams, with drag-and-drop planning and real-time updates.
+    tags: [Turbo Streams, Stimulus, Action Cable]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-cadence.png
+
+  - name: Inkwell
+    by: Quill Co
+    blurb: A minimalist publishing platform with Markdown authoring, drafts, and scheduled posts.
+    tags: [Action Text, Active Storage, Sitemaps]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-inkwell.png
+
+  - name: Tindra
+    by: Northbound
+    blurb: A lightweight e-commerce storefront with a product catalog, cart, and Stripe checkout.
+    tags: [Active Record, Stripe, Hotwire]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-tindra.png
+
+  - name: Relay
+    by: Cobalt
+    blurb: A simple sales CRM — contacts, deals, and a visual pipeline for closing more business.
+    tags: [PostgreSQL, Turbo, Pundit]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-relay.png
+
+  - name: Pulse
+    by: Signalbox
+    blurb: A privacy-friendly product analytics dashboard with funnels, events, and cohort reports.
+    tags: [Solid Queue, Chartkick, Caching]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-pulse.png
+
+  - name: Roundtable
+    by: Commons
+    blurb: A community discussion forum with threaded topics, categories, and reputation.
+    tags: [Action Text, Full-text search, Hotwire]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-roundtable.png
+
+  - name: Slate
+    by: Daypart
+    blurb: An appointment scheduling app with availability, bookings, and calendar sync.
+    tags: [Active Job, iCal, Time zones]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-slate.png
+
+  - name: Compendium
+    by: Archive
+    blurb: A team knowledge base and wiki with spaces, nested docs, and instant search.
+    tags: [Action Text, Search, Versioning]
+    repo: "#"
+    screenshot: /assets/images/reference-apps/mock-compendium.png

_pages/docs.html

@@ -156,6 +156,27 @@ <h3>Contribute to Rails</h3>
           </div>
         </a>
       </div>
+
+      <div class="card">
+        <a href="/docs/reference-apps" title="Reference Apps">
+          <div class="card__body">
+            <div class="card__label">
+              <h6>Reference</h6>
+            </div>
+
+            <div class="card__headline">
+              <h3>Study reference apps</h3>
+            </div>
+
+            <div class="card__content">
+              <p>
+                Read a curated library of exemplary open-source Rails apps to
+                see how real apps are built.
+              </p>
+            </div>
+          </div>
+        </a>
+      </div>
     </div>
   </div>
 </div>

_pages/reference-apps.html

@@ -0,0 +1,89 @@
+---
+title: "Reference Apps — Ruby on Rails"
+description: "A curated library of exemplary open-source Rails apps, hand-picked to show how real, production-quality Rails applications are built."
+permalink: /docs/reference-apps
+redirect_from:
+  - /docs/reference-apps/
+---
+
+<div class="docs heading common-padding--bottom common-padding--top-small">
+  <div class="container">
+    <div class="heading__body">
+      <div class="heading__headline common-headline">
+        <h1>
+          Learn from real,<br />
+          open-source Rails apps.
+        </h1>
+        <p>
+          A small, hand-picked library of exemplary open-source apps worth
+          reading to see how production-quality Rails is built today.
+        </p>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="docs cards reference-apps common-padding--bottom-small">
+  <div class="container">
+    <div class="cards__container">
+      {% for app in site.data.reference_apps.apps %}
+      <div class="card">
+        <a href="{{ app.repo }}" aria-label="{{ app.name }} source code">
+          <div class="card__body">
+            {% if app.screenshot %}
+            <img
+              class="reference-apps__shot"
+              src="{{ app.screenshot }}"
+              alt=""
+              {% unless forloop.first %}loading="lazy"{% endunless %}
+            />
+            {% endif %}
+
+            <div class="reference-apps__text">
+              {% if app.by %}
+              <div class="card__label">
+                <h6>{{ app.by }}</h6>
+              </div>
+              {% endif %}
+
+              <div class="card__headline">
+                <h3>{{ app.name }}</h3>
+              </div>
+
+              <div class="card__content">
+                {% if app.blurb %}<p>{{ app.blurb }}</p>{% endif %}
+
+                {% if app.tags %}
+                <ul class="reference-apps__tags">
+                  {% for tag in app.tags %}
+                  <li>{{ tag }}</li>
+                  {% endfor %}
+                </ul>
+                {% endif %}
+              </div>
+            </div>
+          </div>
+        </a>
+      </div>
+      {% endfor %}
+    </div>
+  </div>
+</div>
+
+<div class="docs text common-padding--bottom">
+  <div class="container">
+    <div class="text__body">
+      <div class="text__content common-content">
+        <hr class="divider" />
+        <h3>About this library</h3>
+        <p>
+          This is a curated library, and the bar for inclusion is intentionally
+          high. An app is listed here only if it is open source under a
+          permissive license, written in idiomatic and modern Rails, and worth
+          reading end to end to learn how a real, production-quality Rails
+          application is built.
+        </p>
+      </div>
+    </div>
+  </div>
+</div>

_sass/modules/_reference-apps.scss

@@ -0,0 +1,128 @@
+// Reference Apps library — an image-led variant of the docs card grid.
+// The default docs cards are fixed-height, centered, and absolutely
+// positioned; these cards lead with a screenshot and size to their content.
+.reference-apps {
+  // Breathing room between the heading/subtitle and the grid. Cards stretch
+  // to equal height per row (default align-items: stretch); the tags are
+  // pushed to the bottom of each card so rows stay tidy.
+  .cards__container {
+    margin-top: 50px;
+  }
+
+  .card {
+    height: auto !important;
+    max-height: none !important;
+
+    a,
+    .card__body {
+      position: static;
+      height: 100%;
+    }
+
+    // Keep the author eyebrow legible on hover (the base card turns
+    // .card__label h6 red, which would hide our red-on-transparent text).
+    a:hover .card__label h6 {
+      background: transparent;
+    }
+  }
+
+  // Image flush to the card edges; overflow:hidden clips it to the
+  // rounded top corners. Content padding lives on the text wrapper.
+  .card__body {
+    align-items: stretch;
+    height: 100%;
+    overflow: hidden;
+    padding: 0;
+  }
+
+  &__shot {
+    aspect-ratio: 16 / 9;
+    background: $color-grey-1;
+    border-bottom: 1px solid rgba($color-black, 0.08);
+    display: block;
+    object-fit: cover;
+    object-position: top center;
+    width: 100%;
+  }
+
+  &__text {
+    box-sizing: border-box;
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    padding: 25px;
+    text-align: left;
+    width: 100%;
+  }
+
+  // Author eyebrow — restyle the floating red badge as inline red text.
+  .card__label {
+    margin-bottom: 6px;
+    position: static;
+    width: auto;
+
+    h6 {
+      background: transparent;
+      color: $color-red;
+      letter-spacing: 0.1em;
+      padding: 0;
+
+      &:after {
+        display: none;
+      }
+    }
+  }
+
+  // Neutralize the base card's 30px side margins and vertical padding so
+  // the headline and blurb align flush with the eyebrow and the wrapper's
+  // own 25px padding.
+  .card__headline,
+  .card__content {
+    margin-left: 0;
+    margin-right: 0;
+  }
+
+  .card__headline {
+    padding-top: 0;
+
+    h3 {
+      margin-left: 0;
+      margin-right: 0;
+    }
+  }
+
+  .card__content {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    padding-bottom: 0;
+
+    p {
+      margin-left: 0;
+      margin-right: 0;
+    }
+  }
+
+  // Scoped under .card__content to override the default
+  // `.cards .card__content ul { list-style-type: disc }` rule.
+  .card__content ul.reference-apps__tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    list-style: none;
+    margin-top: auto; // hug the bottom of the card
+    padding: 18px 0 0; // guaranteed gap above the tags
+
+    li {
+      background: rgba($color-black, 0.05);
+      border-radius: 3px;
+      color: $color-grey-5;
+      font-size: 12px;
+      font-weight: 600;
+      letter-spacing: 0.04em;
+      line-height: 1;
+      padding: 6px 10px;
+      text-transform: uppercase;
+    }
+  }
+}

assets/css/style.scss

@@ -39,6 +39,7 @@
 @import "modules/nav";
 @import "modules/notification";
 @import "modules/post";
+@import "modules/reference-apps";
 @import "modules/text";
 @import "modules/trusted";
 @import "modules/video";