its-swiss 0.7.2 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f884ebf4471bd9c1bdc232a35cf327949466b3db98748a6bb008f985314e091
-  data.tar.gz: d8a1e3b75d21f52e96850a57adf3dcbc72242638f9f7d62fe71126bf8ffa5272
+  metadata.gz: 7ab6df97c9cfca52b616b05f5e985aa37df4253563fd1b1177c9c67890706cad
+  data.tar.gz: 6e9d6316b70b2670b7b307b33ec64955e88d562d085c95a86e07836e635d1a97
 SHA512:
-  metadata.gz: 5157d8c0cd8ad7db0db4025199d76ce4888ed2ad85d4ffb69a4427c97539482f646f56fe1fb274c831cf9f4d4a99a02185e9eb230cbc6516294bb805f631f815
-  data.tar.gz: 7a2ca8413c7cfdaa998a033bdeb9cae176cf7487cdab8af8162b784d01006f264c835a092a11f48bff1c549459dd61166259b6ca9f73771cd3241d0bbfc1430c
+  metadata.gz: 5a3f8671a25c996f2883add93ead145a89244a8a5bbec670022c0b3d49d587d19dd1b5a664eb94bd49908b1d8a4b28877e66b180ac49d3b653b47b0493cf7d02
+  data.tar.gz: 286de25b2203d9928f9a4cbf596341aa8d450c3cfaecf016cafff44737586df4d4cd65d98271d102f2dcf2af9e8f9e058413ead233ad86602a3e242a5f471a4d

data/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 Semver. Consumers pin `~> 0.1`.
 
+## 0.9.1 — 2026-09-07
+
+### Fixed
+
+- **The suite, and so the release, under json 3.0.0.** json 3.0.0 came out
+  twenty minutes after 0.9.0's pull request went green and changed the
+  signature of `JSON.parse`; Active Support 8.1.3.1 still calls it the old
+  way when it reads a signed cookie, so the session and the flash raised on
+  every request and the release of 0.9.0 stopped at its own tests. The
+  Gemfile holds json below 3 until a Rails that takes it. Nothing in the
+  library changed; 0.9.1 is 0.9.0 released.
+
+## 0.9.0 — 2026-09-07
+
+A day of use, and what a day asks of a style: less talk and one red.
+
+### Added
+
+- **Sections.** `page_head(title, sections:)` names the surfaces of one
+  page under its title — what a thing is made of, what it wears, how it
+  leaves — the one shown in the weight, and a page shows that one alone.
+  A working page must not scroll: what is done daily is reached from the
+  head, in the same position on every page, never by scrolling past what
+  was done yesterday. `page_sections(sections)` writes the nav on its own.
+
+- **Explanations.** `explain(text)` puts what a section means behind one
+  mark: a question mark on the line, closed, and the text in the hint
+  register under it when it is asked for. A sentence over every table is
+  needed on the first day and never again.
+
+### Changed
+
+- **One red per page.** The chosen filter and a current menu are in the
+  weight, in ink. The accent is for where you are on the site — the nav,
+  the subnav, the page numbers — and for the one thing that cannot be
+  undone. A page that said "this one" in red five times above the fold
+  had no signal left.
+
+- **Hints are prose.** `.hint` is set at body size. The small size is for
+  labels and metadata, and a hint set in it at a body line's leading read
+  as a list of afterthoughts. Table headings go the other way: the label
+  register, bold, on the line.
+
+- **The filter block is ruled once, below.** The rule above it was a third
+  rule in ten lines, and the rule is the one mark this style draws.
+
+## 0.8.0 — 2026-09-07
+
+The third consumer, and what it and the second found in common.
+
+### Added
+
+- **A page head.** `page_head(title, lede:) { actions }` writes the one
+  shape every page opens with: the title in the page-title register, its
+  lede when it has one, and the actions in a run beside them, wrapping
+  under the title when the page is narrow. Pandatone, Stripeclub and
+  Badger had each drawn their own, and no two agreed on the size of the
+  title or where the buttons went. The document is titled from it unless
+  the view has titled itself.
+
+- **Filters.** A block of registers that narrow a list, each a quiet label
+  and then the choices, in the same two positions every time — a search, a
+  tag, an order, a size are the same kind of control, and are built the
+  same way. `filter_register(label, choices, name:)` writes one; the choice
+  in force carries `aria-current`, which the CSS colours and weights, for
+  the reason the nav says it twice. `search_form(url, frame:, keep:)`
+  writes the first register: a search that narrows the list as you type,
+  into the Turbo Frame named, carrying the other choices so a search does
+  not drop them. Two slots go with it: `--filter-label`, the column the
+  labels occupy, and `--card`.
+
+- **Cards.** `.cards` on a `.grid` lays a list out on the page's own
+  fields, each item `--card` fields wide, two lines between the rows.
+  `.card__link`, `.card__figure`, `.card__name`, `.card__meta` are the
+  parts. No box: the picture is the only filled area a card has.
+
+- **A menu in the nav, and a subnav under the masthead.** `nav_menu(label,
+  current:) { links }` is a destination that opens into destinations — a
+  details element, so it opens with no script — and carries the accent and
+  the weight when where you are is inside it. The shell renders `:subnav`,
+  when an application fills it, as a shaded band under the masthead: a
+  second layer of destinations, inside the one you are in. A host that
+  carries several tools puts the tools in the menu and each tool's own
+  sections in the band.
+
+- **A live search controller.** `its_swiss/live_search_controller.js`,
+  pinned by the engine like the clipboard, submits a search form as you
+  type and takes away the button it makes redundant. The host registers it
+  as `its-swiss-live-search`, beside the clipboard.
+
+### Changed
+
+- The micro register and the quiet colour take `.filter__label` and
+  `.card__meta`.
+
 ## 0.7.2 — 2026-09-04
 
 ### Changed

data/README.md

@@ -34,7 +34,7 @@ current one at `/<version>.html` for anything that needs to pin.
 | In the gem | Stays in the application |
 | --- | --- |
 | Tokens, reset, base typography | The grid itself — which blocks span which fields |
-| Masthead, nav, footer, table, form, button, definition list, pagination | Domain components |
+| Masthead, nav, page head, footer, table, form, button, definition list, pagination, filters, cards | Domain components |
 | A base layout shell with `content_for` slots | Page layouts beyond the shell |
 | View transition names and durations | Which pages transition to which |
 | The value scale and the accent slot | Any hue, any palette knowledge |
@@ -71,6 +71,8 @@ holding all of them. Nothing here has a default the gem could pick honestly.
 | `--columns`, `--gutter` | How many fields this problem has |
 | `--line` | The baseline: the interval everything vertical registers to |
 | `--ratio` | A picture's aspect ratio, per figure — the library cannot read one |
+| `--card` | How many fields a card takes, and at which widths |
+| `--filter-label` | The column a filter's label occupies, so every register's choices start on one line |
 | `--face-150`, `--face-200`, `--face-100` | Read, not set: the face a register names for its ratio of leading to size |
 
 ### The baseline
@@ -313,6 +315,83 @@ it stops on a field line:
 --measure: calc(var(--field) * 3 + var(--gutter) * 2);
 ```
 
+### The page head
+
+What a page is and what can be done to it, in one shape on every page: the
+title in the page-title register, its lede when it has one, and the actions in
+a run beside them, wrapping under the title when the page is narrow.
+
+```erb
+<%= page_head "Palettes", lede: "Every palette in the library." do %>
+  <%= link_to "New palette", new_palette_path, class: "button button--primary" %>
+<% end %>
+```
+
+The document is titled from it unless the view has already set `:title`.
+
+A page with several surfaces — what a thing is made of, what it wears, how it
+leaves — names them under the title with `sections:`, each a name, a URL and
+whether it is the one shown, and shows that one alone. A working page must
+not scroll: what is done daily is reached from the head, in the same position
+on every page.
+
+```erb
+<%= page_head @pattern.name, sections: [ [ "Compose", pattern_path(@pattern), @section == "compose" ],
+                                         [ "Dress", pattern_path(@pattern, section: "dress"), @section == "dress" ] ] do %>
+```
+
+### Explanations
+
+What a section means, behind one mark. A sentence over every table is needed
+on the first day and never again, and a tool used daily is read on every
+other day; so `explain` writes it in the hint register, closed, and a
+question mark on the line opens it.
+
+```erb
+<%= explain "The repeat, in order along the stripe normal." %>
+```
+
+### Filters and cards
+
+What narrows a list, and the list. A search that filters as you type, and a
+register for each other way of narrowing it — a tag, an order, a size — in the
+same two positions every time: a quiet label, then the choices, the one in
+force carrying `aria-current`, which the CSS sets in the weight. In ink, not
+the accent: the accent is for where you are on the site and for the one
+thing that cannot be undone, and a page has one red.
+
+```erb
+<div class="filters">
+  <%= search_form palettes_path, frame: "palettes", keep: { tag: params[:tag], sort: params[:sort] } %>
+  <%= filter_register "Tagged", [ [ "All", palettes_path, params[:tag].blank? ],
+                                  *tags.map { |t| [ t, palettes_path(tag: t), params[:tag] == t ] } ],
+        name: "tag" %>
+</div>
+
+<%= turbo_frame_tag "palettes", target: "_top" do %>
+  <ul class="grid cards">
+    <li class="card">
+      <a class="card__link" href="…">
+        <figure class="card__figure figure" style="--ratio: 1.5"><img src="…" alt=""></figure>
+        <span class="card__name">Brand Core</span>
+      </a>
+      <span class="card__meta">4 swatches</span>
+    </li>
+  </ul>
+<% end %>
+```
+
+The search form belongs outside the frame it fills, so only the results are
+replaced and the field keeps its cursor. `keep:` carries the other choices as
+hidden fields, so a search does not drop the tag or the order you were reading
+in. The button is there for a browser that runs no script; the controller
+takes it away once it has connected.
+
+A card is `--card` fields wide on the page's own grid — say how many once, and
+again at each width that changes it. The picture is a `.figure` with its
+`--ratio` declared, so its box is whole lines at any width and the name under
+it stays on the grid.
+
 ## The layout shell
 
 The installer writes `app/views/layouts/application.html.erb` as a layout
@@ -345,6 +424,7 @@ Slots, all optional:
 | `:head` | Anything else that belongs in `<head>` |
 | `:mark` | The wordmark. No mark and no nav means no masthead at all |
 | `:nav` | The destinations |
+| `:subnav` | A second layer of destinations, inside the one you are in: a shaded band under the masthead |
 | `:main_class` | What the page's main region is, if it is a grid |
 | `:footer` | Whatever belongs after the page |
 
@@ -359,9 +439,15 @@ beyond the shell is the application's, for the same reason its grid is.
 | `its_swiss_stylesheet_tags` | The seven links, tracked for Turbo |
 | `its_swiss_typeface(regular:, bold:)` | The application's typeface, declared under the library's face names |
 | `nav_link_to(name, url, current:)` | A destination, with `aria-current` when you are at it |
+| `nav_menu(label, current:) { links }` | A destination that opens into destinations, with no script |
 | `copy_button(value)` | A value that copies itself |
 | `its_swiss_form_with(...)` | `form_with`, already holding the library's builder |
 | `its_swiss_page_numbers(page, pages)` | Which numbers a run of them shows, elided |
+| `page_head(title, lede:, sections:) { actions }` | The one shape every page opens with |
+| `page_sections(sections)` | The surfaces of one page, the one shown in the weight |
+| `explain(text) { }` | What a section means, behind one mark |
+| `filter_register(label, choices, name:)` | One register of a filter block |
+| `search_form(url, frame:, keep:)` | A search that narrows a list as you type |
 
 ### Pagination
 
@@ -376,6 +462,24 @@ a page, a total, and something that turns a number into a URL:
 Long runs are elided around the current page. `window:` (default 2) sets how
 many neighbours show; `label:` names the `<nav>` for a screen reader.
 
+### JavaScript
+
+Two Stimulus controllers, pinned by the engine so an application that upgrades
+the gem gets the new file without touching its importmap. They are outside
+`controllers/`, so an application registers them by hand, once:
+
+```js
+// app/javascript/controllers/index.js
+import ItsSwissClipboardController from "its_swiss/clipboard_controller"
+import ItsSwissLiveSearchController from "its_swiss/live_search_controller"
+application.register("its-swiss-clipboard", ItsSwissClipboardController)
+application.register("its-swiss-live-search", ItsSwissLiveSearchController)
+```
+
+`copy_button` and `search_form` write the `data-controller` attributes; a page
+without the registrations still works, with the value selectable and the
+search's button on the page.
+
 ## The form builder
 
 One shape for every field: a label, a control, and — when there is something to
@@ -464,7 +568,8 @@ ladder; the names are the library's rather than the application's.
 | `.masthead__nav` | `.nav` |
 | `.channels` | `.pairs` |
 | `.form`, `.field`, `.button*`, `.copy`, `.errors`, `.hint`, `.empty` | unchanged |
-| `--columns-dense`, `--card`, `--card-wide`, `.swatch*`, `.tag*`, `.filter*` | stay in Pandatone |
+| `.tag*`, `.filter*`, `.page-head`, `live-search` | `.filter*`, `.page-head`, `.cards`, `its-swiss-live-search` — in the gem since 0.8.0 |
+| `--columns-dense`, `--card-wide`, `.swatch*` | stay in Pandatone |
 
 Two behavioural differences to know about:
 

data/app/assets/javascripts/its_swiss/live_search_controller.js

@@ -0,0 +1,31 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Submits a search form as you type, into the Turbo Frame it targets.
+//
+// The filtering stays on the server, in the same scope the button uses: one
+// definition of what a search matches, not a Ruby one and a drifting
+// JavaScript copy. The form sits outside its frame so only the results are
+// replaced and the field keeps its focus and its cursor.
+//
+// The button goes when this connects, because from that moment it is a second
+// way to do the thing that has just been done. It is hidden here rather than
+// left out of the markup for the browser that never runs this: without the
+// controller the button is the only way to search, so it has to be on the
+// page for the page to work.
+export default class extends Controller {
+  static targets = [ "submit" ]
+  static values = { delay: { type: Number, default: 200 } }
+
+  connect() {
+    if (this.hasSubmitTarget) this.submitTarget.hidden = true
+  }
+
+  search() {
+    clearTimeout(this.timeout)
+    this.timeout = setTimeout(() => this.element.requestSubmit(), this.delayValue)
+  }
+
+  disconnect() {
+    clearTimeout(this.timeout)
+  }
+}

data/app/assets/stylesheets/its_swiss/components.css

@@ -70,6 +70,92 @@
     font-weight: 700;
   }
 
+  /* A menu in the nav: a destination that opens into destinations. A
+     details element, so it opens and closes with no script, and a summary
+     set like the other destinations with a small mark that says it opens.
+     The list floats under it on paper with a keyline, the one floating box
+     in the style — a menu that pushed the page down would not be a menu. */
+  .menu {
+    position: relative;
+  }
+
+  .menu > summary {
+    list-style: none;
+    cursor: pointer;
+    white-space: nowrap;
+  }
+
+  .menu > summary::-webkit-details-marker { display: none; }
+
+  .menu > summary::after {
+    content: " \25BE";
+    color: var(--ink-quiet);
+  }
+
+  .menu > summary:hover,
+  .menu[open] > summary { color: var(--ink); }
+
+  /* Where you are, when where you are is inside the menu: the weight, in
+     ink. Not the accent — a page has one red, and the subnav under a menu
+     that is current already names the place in it. */
+  .menu--current > summary {
+    color: var(--ink);
+    font-weight: 700;
+  }
+
+  /* Out of the flow, but still on the grid: a line of padding above and
+     below, and the keyline drawn inside, so every link in it sits on a
+     line of the page under it. */
+  .menu__list {
+    position: absolute;
+    inset-inline-start: calc(-1 * var(--space-2));
+    top: 100%;
+    z-index: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: max-content;
+    padding: var(--line) var(--space-2);
+    background: var(--paper);
+    box-shadow: inset 0 0 0 var(--rule-hair) var(--rule);
+  }
+
+  .menu__list a {
+    display: block;
+    text-decoration: none;
+  }
+
+  .menu__list a:hover { color: var(--ink); }
+
+  /* --- Subnav -------------------------------------------------------------
+     A second layer of destinations, inside the one you are in: what a tool
+     has beside what the application has. A shaded band under the masthead,
+     three lines tall the way the masthead is, with the same run of links
+     the nav has and the same marking of where you are. Rendered by the
+     shell when the application fills :subnav, and not at all otherwise. */
+  /* The rule is drawn inside the band rather than under it, so the band and
+     the page inside it are both three whole lines. */
+  .subnav {
+    background: var(--paper-shaded);
+    box-shadow: inset 0 calc(-1 * var(--rule-hair)) 0 var(--rule);
+  }
+
+  .subnav > .page {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: end;
+    gap: var(--line) var(--space-3);
+    padding-block: var(--line);
+  }
+
+  .subnav a { text-decoration: none; }
+
+  .subnav a:hover { color: var(--ink); }
+
+  .subnav [aria-current="page"] {
+    color: var(--accent);
+    font-weight: 700;
+  }
+
   /* --- Footer -------------------------------------------------------------
      A hairline, the micro register, and whatever the application has to say
      after the page. It carries no links of its own: what belongs down there
@@ -89,6 +175,94 @@
     line-height: var(--line);
   }
 
+  /* --- Page head ----------------------------------------------------------
+     What a page is and what can be done to it. The title and, when it has
+     one, its lede on the left; the actions on the right, wrapping under
+     the title when the page is narrow. Everything after it starts two
+     lines down, which is the gap a section gets.
+
+     One shape for every page, so a reader arriving from another application
+     set in this style already knows where the name is and where the buttons
+     are. The title is the page-title register: a page has one, and it is
+     the largest thing on it. */
+
+  .page-head {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    align-items: flex-start;
+    gap: var(--line) var(--space-3);
+    margin-block-end: var(--line-2);
+  }
+
+  /* The title takes the measure and the actions take what they need. A
+     basis rather than a share, so a long name wraps inside the measure
+     instead of pushing the actions off the line. */
+  .page-head__title {
+    flex: 1 1 var(--measure);
+    min-width: 0;
+  }
+
+  /* The actions shrink to their widest button and wrap inside it, rather
+     than holding their one-line width and pushing a phone's page sideways. */
+  .page-head__actions { flex: 0 1 auto; }
+
+  /* --- Sections -----------------------------------------------------------
+     One page, several surfaces: what a thing is made of, what it wears,
+     how it leaves. A run of names under the title, the one you are on in
+     the weight, and the surface below it the only thing on the page. A
+     working page must not scroll: what is done every day is reached from
+     the head, in the same position on every page, and never by scrolling
+     past what was done yesterday. */
+  .sections {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--line) var(--space-3);
+  }
+
+  /* Its own row in the head, under the title and the actions. */
+  .page-head > .sections { flex-basis: 100%; }
+
+  .sections a {
+    display: inline-block;
+    color: var(--ink-quiet);
+    text-decoration: none;
+  }
+
+  .sections a:hover { color: var(--ink); }
+
+  /* Where you are, in the weight. Ink, not the accent: the accent is for
+     where you are on the site, and this is where you are on the page. */
+  .sections [aria-current] {
+    color: var(--ink);
+    font-weight: 700;
+  }
+
+  /* --- Explanations -------------------------------------------------------
+     What a section means, behind one mark, for the day it is first read.
+     A sentence over every table is needed on the first day and never
+     again, and a tool used daily is read on every other day. So the
+     explanation is there, in the hint register, and closed: a question
+     mark on the line, and the text under it when it is asked for. A
+     details element, so it opens with no script. */
+  /* A block as wide as its one character, so the line it sits on is whole
+     and the target is the mark and not the row. */
+  .explain > summary {
+    list-style: none;
+    display: block;
+    width: max-content;
+    cursor: pointer;
+    color: var(--ink-quiet);
+    font-weight: 700;
+  }
+
+  .explain > summary::-webkit-details-marker { display: none; }
+
+  .explain > summary:hover,
+  .explain[open] > summary { color: var(--ink); }
+
+  .explain__body { margin-block-start: var(--line); }
+
   /* --- Rules --------------------------------------------------------------
      The one horizontal mark in the style, at the two weights tokens.css
      declares. */
@@ -184,9 +358,15 @@
     vertical-align: top;
   }
 
+  /* A heading is a label: the label register, bold, on the line. Body size
+     made it a second row of values. */
   .table th {
+    font-family: var(--face-200), var(--font-family);
+    font-size: var(--size-1);
+    line-height: var(--line);
     color: var(--ink-quiet);
     font-weight: 700;
+    letter-spacing: 0.01em;
   }
 
   .table thead th { border-bottom-color: var(--ink); }
@@ -490,6 +670,141 @@
 
   .pagination__gap { color: var(--ink-quiet); }
 
+  /* --- Filters ------------------------------------------------------------
+     What narrows a list. One shape for every way of narrowing it — a
+     search, a tag, an order, a size — because they are the same kind of
+     control: pick one of a handful. A register is a quiet label and then
+     the choices, in the same two positions every time, so filtering and
+     ordering read as the registers they are rather than as two rows of
+     identical words. Ruled below, once: the block belongs to the list
+     under it, and the space above it is the page head's. A second rule
+     above it was a third rule in ten lines, and the rule is the one mark
+     this style draws, so it has to be rare. */
+
+  .filters {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+    gap: var(--line) var(--space-3);
+    /* The rule is drawn inside the box, so the block stays whole lines. */
+    padding-block-end: calc(var(--line) - var(--rule-hair));
+    border-block-end: var(--rule-hair) solid var(--rule);
+    margin-block-end: var(--line);
+  }
+
+  .filter {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+    flex-basis: 100%;
+    gap: var(--line) var(--space-2);
+  }
+
+  /* The label column. A width off the ladder, so every register's choices
+     start on the same line down the page rather than a few pixels apart
+     because one word is longer than another. An application with longer
+     labels sets --filter-label once. */
+  .filter__label,
+  .filters .form--inline label { min-width: var(--filter-label); }
+
+  .filter__choices {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--line) var(--space-2);
+  }
+
+  /* The choices are the flex items themselves, the way the nav's
+     destinations are: blockified, so each is a line box that is the tap
+     target and can be trimmed where the faces are not honoured. A list
+     item between them would be a second box to correct. */
+  .filter__choices a {
+    color: var(--ink-quiet);
+    text-decoration: none;
+  }
+
+  .filter__choices a:hover { color: var(--ink); }
+
+  /* Which one is chosen: the weight, in ink. The accent is for where you
+     are on the site and for the one thing that cannot be undone; a page
+     with four registers each saying "this one" in red has no signal left. */
+  .filter__choices [aria-current] {
+    color: var(--ink);
+    font-weight: 700;
+  }
+
+  /* The search is the first register, built like the others rather than as
+     a stacked field above them: the label in the label column, the control
+     where the choices start. Label and control meet on the under edge — the
+     label's baseline is its under edge, and the control's text stands on
+     the rule that closes it — so the two read as one line. The button is
+     there for a browser that runs no script and wraps under the field at a
+     phone's width; it goes when the live search connects, because from then
+     on typing has already done what it does. */
+  .filters .form--inline {
+    flex: 1 1 var(--measure);
+    max-width: var(--measure);
+  }
+
+  .filters .form--inline .field--inline {
+    flex: 1 1 auto;
+    align-items: flex-end;
+    min-width: 0;
+  }
+
+  /* A basis of nothing, so the control takes what the row has left rather
+     than the twenty characters a browser gives a text control by default. */
+  .filters .form--inline .field--inline input {
+    flex: 1 1 0;
+    width: auto;
+    min-width: 0;
+  }
+
+  /* --- Cards --------------------------------------------------------------
+     A list of things, each a picture over its name and a line about it,
+     laid out on the page's own fields: a card is --card fields wide, and
+     the application says how many, once, at each width it cares about. Two
+     lines between the rows, because a row of cards is a row of sections.
+
+     No box. A card is the thing itself, and the picture is the only filled
+     area it has; what separates one from the next is the gutter. */
+
+  .cards { row-gap: var(--line-2); }
+
+  .cards > * {
+    --span: var(--card);
+    min-width: 0;
+  }
+
+  /* The picture and the name are one link, so a card costs one tab stop and
+     announces its destination once. */
+  .card__link {
+    display: block;
+    color: inherit;
+    text-decoration: none;
+  }
+
+  .card__link:hover .card__name {
+    text-decoration: underline;
+    text-underline-offset: 0.2em;
+  }
+
+  /* The picture is a .figure with its --ratio declared, so its box is a
+     whole number of lines at any width and the name under it stays on the
+     grid; what this adds is the line between them. */
+  .card__figure { margin-block-end: var(--line); }
+
+  /* Blocks, so each is a line of its own and can be trimmed where the faces
+     are not honoured. */
+  .card__name,
+  .card__meta { display: block; }
+
+  .card__name {
+    font-family: var(--face-150), var(--font-family);
+    font-size: var(--size-2);
+    line-height: var(--line);
+    font-weight: 700;
+  }
+
   /* --- What a page has to say --------------------------------------------
      Three registers: it worked, it was refused, there is nothing here. The
      refusal is the only one that interrupts, and it interrupts with a rule

data/app/assets/stylesheets/its_swiss/tokens.css

@@ -181,6 +181,14 @@
     );
     --measure: calc(var(--field) * 3 + var(--gutter) * 2);
 
+    /* --- Lists -------------------------------------------------------------
+       Two more slots an index fills. How many fields a card takes, which is
+       the application's to say and to change at each width it cares about;
+       and the column a filter's label occupies, so the choices of every
+       register start on one line down the page. */
+    --card: 1;
+    --filter-label: var(--space-8);
+
     /* --- Transitions -------------------------------------------------------
        The page crossfade is short enough to read as a replacement rather than
        an animation. A morph runs longer, because the thing travelling has to

data/app/assets/stylesheets/its_swiss/type.css

@@ -81,7 +81,9 @@
   caption,
   legend,
   label,
-  .field label {
+  .field label,
+  .filter__label,
+  .card__meta {
     font-family: var(--face-200), var(--font-family);
     font-size: var(--size-1);
     line-height: var(--line);
@@ -93,16 +95,23 @@
      picking a gray. */
   .quiet,
   .hint,
+  .filter__label,
+  .card__meta,
   .nav a,
+  .menu > summary,
+  .subnav a,
   .footer,
   .pairs dt,
   .button--quiet,
   .button--danger,
   .link-quiet { color: var(--ink-quiet); }
 
+  /* A hint is prose — a sentence about the thing beside it — and prose is
+     read at body size. The small size is for labels and metadata, and a
+     hint set in it read as a list of afterthoughts. */
   .hint {
-    font-family: var(--face-200), var(--font-family);
-    font-size: var(--size-1);
+    font-family: var(--face-150), var(--font-family);
+    font-size: var(--size-2);
     line-height: var(--line);
     max-width: var(--measure);
   }
@@ -119,6 +128,8 @@
      inherited, because a button does not inherit a font and a nav may sit
      inside a register that is not the body's. */
   .nav a,
+  .menu > summary,
+  .subnav a,
   .button {
     font-family: var(--face-150), var(--font-family);
     font-size: var(--size-2);
@@ -220,11 +231,18 @@
       .page-title,
       h1, h2, h3, h4,
       p, dt, th, td, figcaption, caption, legend, label,
-      li:not(:has(> :is(p, ul, ol, dl, div, figure, table, pre, blockquote))),
+      li:not(:has(> :is(p, ul, ol, dl, div, figure, table, pre, blockquote, .card__link))),
       dd:not(:has(> :is(p, ul, ol, dl, div, figure, table, pre, blockquote))),
       .micro, .hint, .lede, .empty, .masthead__mark, .field__error, .errors__title,
+      .filter__label, .card__name, .card__meta,
+      .explain > summary,
       /* Flex items are blockified, so the text in a row is trimmable too. */
       .nav a,
+      .sections a,
+      .menu > summary,
+      .menu__list a,
+      .subnav a,
+      .filter__choices a,
       .pagination a,
       .pagination [aria-current],
       .pagination__gap,

data/app/helpers/its_swiss/application_helper.rb

@@ -80,6 +80,21 @@ module ItsSwiss
       link_to(name, url, **options, &block)
     end
 
+    # A destination in the nav that opens into destinations: a details
+    # element with the label as its summary and the block as its list, so it
+    # opens and closes with no script. current: when one of the destinations
+    # inside is where you are, the summary carries the accent and the weight
+    # the way a current link does.
+    #
+    #   <%= nav_menu "Tools", current: in_a_tool? do %>
+    #     <%= nav_link_to "Pandatone", "/pandatone", current: in_engine?(pandatone) %>
+    #   <% end %>
+    def nav_menu(label, current: false, &block)
+      tag.details(class: token_list("menu", ("menu--current" if current))) do
+        safe_join([ tag.summary(label), tag.div(capture(&block), class: "menu__list") ])
+      end
+    end
+
     # A value on screen exists to be taken somewhere else, so it is a button
     # that copies itself. The value stays visible text inside it, which is
     # what keeps it usable when the clipboard is not available at all.
@@ -133,6 +148,105 @@ module ItsSwiss
     end
     private :its_swiss_face
 
+    # What a page is and what can be done to it: the title, a lede when the
+    # page has one, and the actions in the block. One shape for every page,
+    # and the document is titled from it unless the view has titled itself.
+    #
+    #   <%= page_head "Palettes", lede: "Every palette in the library." do %>
+    #     <%= link_to "New palette", new_palette_path, class: "button button--primary" %>
+    #   <% end %>
+    #
+    # A page with several surfaces names them under the title, and the one
+    # you are on carries the weight:
+    #
+    #   <%= page_head @pattern.name, sections: [ [ "Compose", pattern_path(@pattern), true ],
+    #                                            [ "Dress", pattern_path(@pattern, section: "dress"), false ] ] do %>
+    def page_head(title, lede: nil, sections: nil, &block)
+      content_for(:title, strip_tags(title.to_s)) unless content_for?(:title)
+      actions = capture(&block) if block
+
+      tag.header(class: "page-head") do
+        safe_join([
+          tag.div(class: "page-head__title") do
+            safe_join([ tag.h1(title, class: "page-title"), (tag.p(lede, class: "lede") if lede) ].compact)
+          end,
+          (tag.div(actions, class: "page-head__actions run") if actions.present?),
+          (page_sections(sections) if sections.present?)
+        ].compact)
+      end
+    end
+
+    # The surfaces of one page: a name, a URL and whether it is the one
+    # shown, each a whole navigation so it survives a reload and can be
+    # sent to somebody. The page head places it; on its own it is a nav.
+    def page_sections(sections, label: "Sections")
+      tag.nav(class: "sections", aria: { label: label }) do
+        safe_join(sections.map { |text, url, current| link_to(text, url, aria: { current: ("page" if current) }) })
+      end
+    end
+
+    # What a section means, behind one mark. The explanation is written in
+    # the hint register and closed: a page used daily is read on every day
+    # but the first, and a sentence over every table is for the first.
+    #
+    #   <%= explain "The repeat, in order along the stripe normal." %>
+    #   <%= explain do %><p class="hint">…</p><% end %>
+    def explain(text = nil, label: "Explain", &block)
+      body = block ? capture(&block) : tag.p(text, class: "hint")
+
+      tag.details(class: "explain") do
+        safe_join([ tag.summary("?", aria: { label: label }), tag.div(body, class: "explain__body") ])
+      end
+    end
+
+    # One register of a filter block: a quiet label, then the choices, each
+    # a name, a URL and whether it is the one in force. Filtering and
+    # ordering are the same kind of control — pick one of a handful — so
+    # they are built the same way and told apart by their label.
+    #
+    #   <%= filter_register "Tagged", [ [ "All", colors_path, params[:tag].blank? ],
+    #                                   *tags.map { |t| [ t, colors_path(tag: t), params[:tag] == t ] } ],
+    #         name: "tag" %>
+    #
+    # The one in force carries aria-current, which the CSS colours and
+    # weights, and a test can find without reading a class.
+    def filter_register(label, choices, name: nil)
+      tag.div(class: "filter", data: { filter: name }) do
+        safe_join([
+          tag.span(label, class: "filter__label"),
+          tag.div(class: "filter__choices") do
+            safe_join(choices.map { |text, url, current| link_to(text, url, aria: { current: ("true" if current) }) })
+          end
+        ])
+      end
+    end
+
+    # A search that narrows a list as you type, into the Turbo Frame named.
+    # The form belongs outside that frame, so only the results are replaced
+    # and the field keeps its cursor; the button is for a browser that runs
+    # no script, and the controller takes it away once it has connected.
+    #
+    #   <%= search_form palettes_path, frame: "palettes", keep: { tag: params[:tag], sort: params[:sort] } %>
+    #
+    # keep: the other choices on the page, carried as hidden fields so a
+    # search does not drop the tag or the order you were reading in. The
+    # host registers the controller as its-swiss-live-search.
+    def search_form(url, frame:, param: :q, label: "Search", value: nil, keep: {}, delay: nil, **options)
+      value = params[param] if value.nil? && respond_to?(:params)
+      data = { controller: "its-swiss-live-search", action: "input->its-swiss-live-search#search",
+               turbo_frame: frame, its_swiss_live_search_delay_value: delay }.compact
+
+      form_with(url: url, method: :get, class: token_list("form form--inline", options[:class]), data: data) do
+        safe_join([
+          *keep.compact_blank.map { |name, kept| hidden_field_tag(name, kept, id: nil) },
+          tag.div(class: "field field--inline") do
+            safe_join([ label_tag(param, label), search_field_tag(param, value, autocomplete: "off") ])
+          end,
+          submit_tag(label, name: nil, class: "button", data: { its_swiss_live_search_target: "submit" })
+        ])
+      end
+    end
+
     # form_with, already holding the library's builder. An application that
     # wants its own builder still can; this is the shorthand for the case
     # where it does not.

data/app/views/its_swiss/specimen/_filters.html.erb

@@ -0,0 +1,38 @@
+<section data-specimen="filters">
+  <h3>Filters and cards</h3>
+  <p class="hint">
+    What narrows a list, and the list. A search that filters as you type, and
+    a register for each other way of narrowing it: the same two positions
+    every time, a quiet label and the choices, the one in force carrying the
+    weight. Under it, cards on the page's own fields — this page says a card
+    is two fields wide.
+  </p>
+
+  <div class="filters">
+    <%= search_form "#filters", frame: "specimen-results", value: "", keep: { tag: "print" } %>
+    <%= filter_register "Tagged",
+          [ [ "All", "#filters", false ], [ "print", "#filters", true ], [ "screen", "#filters", false ] ],
+          name: "tag" %>
+    <%= filter_register "Sort by",
+          [ [ "Name", "#filters", true ], [ "Newest", "#filters", false ], [ "Most used", "#filters", false ] ],
+          name: "sort" %>
+  </div>
+
+  <p class="hint">3 of 12 palettes</p>
+
+  <ul class="grid cards" style="--card: 2">
+    <% [ [ "Brand Core", "4 swatches", 1 ], [ "Press", "6 swatches", 2 ], [ "Screen", "3 swatches", 3 ] ].each do |name, meta, value| %>
+      <li class="card">
+        <a class="card__link" href="#filters">
+          <figure class="card__figure figure" style="--ratio: 1.5">
+            <svg viewBox="0 0 3 2" role="img" aria-label="A block of value <%= value %>">
+              <rect width="3" height="2" fill="var(--value-<%= value %>)"/>
+            </svg>
+          </figure>
+          <span class="card__name"><%= name %></span>
+        </a>
+        <span class="card__meta"><%= meta %></span>
+      </li>
+    <% end %>
+  </ul>
+</section>

data/app/views/its_swiss/specimen/_masthead.html.erb

@@ -5,11 +5,30 @@
     <nav class="nav">
       <a href="#masthead" aria-current="page">Where you are</a>
       <a href="#masthead">Somewhere else</a>
-      <a href="#masthead">And another</a>
+      <%= nav_menu "A menu", current: false do %>
+        <a href="#masthead">One of several</a>
+        <a href="#masthead">Another of them</a>
+        <a href="#masthead">And a third</a>
+      <% end %>
+      <%= nav_menu "Where you also are", current: true do %>
+        <a href="#masthead" aria-current="page">Inside the menu</a>
+        <a href="#masthead">Beside it</a>
+      <% end %>
     </nav>
   </header>
+  <nav class="subnav" aria-label="Inside this section">
+    <div class="page">
+      <a href="#masthead">The section's mark</a>
+      <a href="#masthead" aria-current="page">Where you are in it</a>
+      <a href="#masthead">Elsewhere in it</a>
+    </div>
+  </nav>
   <p class="hint">
     The current destination carries the accent and the weight. Two signals,
-    because colour alone is not one.
+    because colour alone is not one. A menu is a destination that opens into
+    destinations, and carries both when where you are is inside it. The
+    subnav is a second layer, inside the one you are in: a shaded band under
+    the masthead, rendered by the shell when the application fills
+    <code>:subnav</code>.
   </p>
 </section>

data/app/views/its_swiss/specimen/_page_head.html.erb

@@ -0,0 +1,33 @@
+<section data-specimen="page-head">
+  <h3>Page head</h3>
+  <p class="hint">
+    What a page is and what can be done to it: the title and its lede on the
+    left, the actions on the right, wrapping under when the page is narrow.
+    One shape for every page, so the name and the buttons are always where
+    they were on the last one.
+  </p>
+  <%= page_head "Palettes", lede: "Every palette in the library, including the ones no colour has claimed yet." do %>
+    <a href="#page-head" class="button button--primary">New palette</a>
+    <a href="#page-head" class="button">Import from a file</a>
+    <a href="#page-head" class="button">New from this</a>
+    <a href="#page-head" class="button button--danger">Delete palette</a>
+  <% end %>
+
+  <h4>Sections</h4>
+  <p class="hint">
+    A page with several surfaces names them under the title, the one shown
+    in the weight, and shows that one alone. What is done daily is reached
+    from the head, never by scrolling past what was done yesterday.
+  </p>
+  <%= page_head "Deck Chair", sections: [ [ "Compose", "#page-head", true ], [ "Dress", "#page-head", false ], [ "Export", "#page-head", false ] ] do %>
+    <a href="#page-head" class="button button--primary">Dress this pattern</a>
+    <a href="#page-head" class="button button--quiet">Rename</a>
+  <% end %>
+
+  <h4>Explanations</h4>
+  <p class="hint">
+    What a section means, behind one mark, for the day it is first read.
+    Closed, in the hint register, and there when it is asked for.
+  </p>
+  <%= explain "The repeat, in order along the stripe normal. Widths sum to one." %>
+</section>

data/app/views/its_swiss/specimen/_take.html.erb

@@ -9,11 +9,13 @@
   <%= render "its_swiss/specimen/type" %>
   <%= render "its_swiss/specimen/grid" %>
   <%= render "its_swiss/specimen/masthead" %>
+  <%= render "its_swiss/specimen/page_head" %>
   <%= render "its_swiss/specimen/buttons" %>
   <%= render "its_swiss/specimen/form" %>
   <%= render "its_swiss/specimen/figure" %>
   <%= render "its_swiss/specimen/table" %>
   <%= render "its_swiss/specimen/pairs" %>
+  <%= render "its_swiss/specimen/filters" %>
   <%= render "its_swiss/specimen/pagination" %>
   <%= render "its_swiss/specimen/messages" %>
   <%= render "its_swiss/specimen/footer" %>

data/app/views/layouts/its_swiss/shell.html.erb

@@ -9,6 +9,7 @@
     :head        anything else that belongs in <head>
     :mark        the wordmark. No mark and no nav means no masthead at all
     :nav         the destinations
+    :subnav      a second layer of destinations, inside the one you are in
     :main_class  what the page's main region is, if it is a grid
     :footer      whatever belongs after the page
 
@@ -48,6 +49,10 @@
 
     <%= render "its_swiss/shared/masthead" %>
 
+    <% if content_for?(:subnav) %>
+      <nav class="subnav" aria-label="Inside this section"><div class="page"><%= content_for(:subnav) %></div></nav>
+    <% end %>
+
     <main id="main" class="page <%= content_for(:main_class) %>">
       <%= render "its_swiss/shared/flash" %>
       <%= yield %>

data/config/importmap.rb

@@ -1,5 +1,7 @@
-# The library's whole JavaScript surface. A typographic system does not need
-# script to set type; this is here because a value that exists to be taken
-# somewhere else should be a button that copies itself, and that cannot be
-# done in CSS.
+# The library's whole JavaScript surface: two controllers. A typographic
+# system does not need script to set type; these are here because a value
+# that exists to be taken somewhere else should be a button that copies
+# itself, and a search should narrow the list as you type, and neither can
+# be done in CSS.
 pin "its_swiss/clipboard_controller", to: "its_swiss/clipboard_controller.js"
+pin "its_swiss/live_search_controller", to: "its_swiss/live_search_controller.js"

data/lib/its_swiss/version.rb

@@ -1,3 +1,3 @@
 module ItsSwiss
-  VERSION = "0.7.2"
+  VERSION = "0.9.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: its-swiss
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.9.1
 platform: ruby
 authors:
 - Bobby Meyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -105,6 +105,7 @@ files:
 - LICENSE
 - README.md
 - app/assets/javascripts/its_swiss/clipboard_controller.js
+- app/assets/javascripts/its_swiss/live_search_controller.js
 - app/assets/stylesheets/its-swiss.css
 - app/assets/stylesheets/its_swiss/components.css
 - app/assets/stylesheets/its_swiss/faces.css
@@ -122,11 +123,13 @@ files:
 - app/views/its_swiss/shared/_pagination.html.erb
 - app/views/its_swiss/specimen/_buttons.html.erb
 - app/views/its_swiss/specimen/_figure.html.erb
+- app/views/its_swiss/specimen/_filters.html.erb
 - app/views/its_swiss/specimen/_footer.html.erb
 - app/views/its_swiss/specimen/_form.html.erb
 - app/views/its_swiss/specimen/_grid.html.erb
 - app/views/its_swiss/specimen/_masthead.html.erb
 - app/views/its_swiss/specimen/_messages.html.erb
+- app/views/its_swiss/specimen/_page_head.html.erb
 - app/views/its_swiss/specimen/_pagination.html.erb
 - app/views/its_swiss/specimen/_pairs.html.erb
 - app/views/its_swiss/specimen/_table.html.erb