@layer components {
  /* Icons — one SVG file each in app/assets/images/icons.
   *
   * They are files, edited and replaced like any other asset, with no generator
   * and no gem between them and the page. The icon helper inlines the file
   * rather than pointing an <img> at it, and that is the whole reason this
   * class exists: an <img> cannot take currentColor, and every icon in the app
   * sits inside something that has already decided its colour — a rail item is
   * --color-ink until it is the page you are on, and then it is the accent,
   * without the icon or the call site saying so.
   *
   * The helper wraps the file rather than reaching into it, so the class list
   * is composed in Ruby and the files stay plain SVG that any editor can open.
   *
   * Sized in em against the text beside it, like every other part of a control,
   * so a size variant on the control carries the icon with it and nothing here
   * has to know a size exists.
   */
  .icon {
    --icon-size: 1.25em;

    display: inline-flex;
    /* Never squeezed by a long label next to it. */
    flex: none;
    inline-size: var(--icon-size);
    block-size: var(--icon-size);

    > svg {
      inline-size: 100%;
      block-size: 100%;
    }
  }

  /* For an icon that trails a label rather than leading it — a chevron, a
     caret — where matching the text is right and out-measuring it is not. */
  .icon--small {
    --icon-size: 1em;
  }

  .icon--large {
    --icon-size: 1.5em;
  }
}