{
  "schema": "design-playbook@1",
  "discipline": "icons",
  "checked_at": "2026-10-29",
  "essence": "One set, one stroke, the weight of the words beside it, and only where an icon says something the text can't.",
  "pick": {
    "prov": "our reading",
    "why": "Apple: match the weight of interface icons to the text beside them. Material: rounded icons go with curved, heavier type; sharp icons with rectangular details. Strokes below are measured at 24px from each set's own files.",
    "inputs": [
      "the brand's published icon stroke, if any",
      "button corner radius",
      "display type weight",
      "body type weight"
    ],
    "rows": [
      {
        "when": "The brand publishes an icon stroke",
        "test": "published_stroke",
        "pick": "the set whose stroke at 24px is closest to the published one, scaled to 24px",
        "lib": "auto",
        "why": "The brand's own number beats our table."
      },
      {
        "when": "Sharp corners: button radius 0–2px",
        "test": "radius<=2",
        "lib": "remix",
        "style": "line",
        "why": "Square terminals and 90° interiors echo rectangular UI."
      },
      {
        "when": "Round brand: pill buttons",
        "test": "radius=pill",
        "lib": "lucide",
        "style": "line",
        "stroke": 2,
        "why": "Round caps and joins everywhere, and a 2px stroke that holds up next to pill buttons."
      },
      {
        "when": "Light type: body weight 300 or less",
        "test": "body<=300",
        "lib": "phosphor",
        "style": "light",
        "why": "A 1.125px stroke at 24px matches thin stems."
      },
      {
        "when": "Heavy type: display weight 700 or more",
        "test": "display>=700",
        "lib": "phosphor",
        "style": "bold",
        "why": "A 2.25px stroke at 24px matches heavy stems."
      },
      {
        "when": "Medium type: display weight 500 or less",
        "test": "display<=500",
        "lib": "heroicons",
        "style": "outline",
        "stroke": 1.5,
        "why": "A 1.5px stroke sits with regular-weight type."
      },
      {
        "when": "Anything else",
        "test": "else",
        "lib": "lucide",
        "style": "line",
        "stroke": 2,
        "why": "The most complete open set, with the most checkable spec."
      }
    ]
  },
  "rules": [
    {
      "id": "one-set",
      "rule": "One icon set and one style per page.",
      "value": "Every icon on the page comes from the same set and style.",
      "check": "Every svg.ic carries the same data-lib and data-style.",
      "sources": [
        "https://lucide.dev/how-to/icon-guide",
        "https://developer.apple.com/design/human-interface-guidelines/icons",
        "https://www.ibm.com/design/language/iconography/ui-icons/usage/"
      ],
      "prov": "published"
    },
    {
      "id": "one-stroke",
      "rule": "One stroke width per rendered size.",
      "value": "Effective stroke = stroke-width × rendered width ÷ viewBox width; all equal within a size.",
      "check": "Compute the effective stroke of every stroked icon at each size; fail if two differ.",
      "sources": [
        "https://developer.apple.com/design/human-interface-guidelines/icons",
        "https://lucide.dev/contribute/icons/specification"
      ],
      "prov": "published"
    },
    {
      "id": "stroke-by-size",
      "rule": "Don't blow a small icon up; above 32px, stop thickening the stroke.",
      "value": "IBM thickens the stroke with size: 1px at 16, 1.25px at 20, 1.5px at 24, 2px at 32. Material's optical-size axis thins strokes at large sizes. Our recipe: above 32px, hold the stroke at the set's 32px value.",
      "check": "Above 32px, effective stroke ≤ the set's stroke at 32px (its 24px stroke × 32 ÷ 24).",
      "sources": [
        "https://www.ibm.com/design/language/iconography/ui-icons/design/",
        "https://primer.style/octicons/usage-guidelines/"
      ],
      "prov": "our recipe",
      "why": "IBM's table stops at 32 and Material thins large icons; holding at 32 is the simplest rule that follows both."
    },
    {
      "id": "match-text",
      "rule": "Match the icon's weight to the text beside it.",
      "value": "Use the pick table: it matches the set's stroke to the brand's type weight and corners.",
      "check": "The page's set and style equal the pick table's row for this brand.",
      "sources": [
        "https://developer.apple.com/design/human-interface-guidelines/sf-symbols"
      ],
      "prov": "published"
    },
    {
      "id": "size-to-text",
      "rule": "Size the icon to the text it sits with.",
      "value": "IBM: a 16px icon with 14px text, a 20px icon with 16px text.",
      "check": "Icon height ÷ label font size is between 1.14 and 1.25 (IBM's two pairs).",
      "sources": [
        "https://www.ibm.com/design/language/iconography/ui-icons/usage/"
      ],
      "prov": "published"
    },
    {
      "id": "center",
      "rule": "Center the icon on the text, don't sit it on the baseline.",
      "value": "Icon center equals the line's center, within 1px.",
      "check": "In a flex row, align-items is center; no inline-block icon has vertical-align baseline.",
      "sources": [
        "https://carbondesignsystem.com/elements/icons/usage/"
      ],
      "prov": "published"
    },
    {
      "id": "current-color",
      "rule": "Draw icons in the text color, one color per icon.",
      "value": "fill or stroke is currentColor; a duotone back layer may be the accent.",
      "check": "Every non-none fill and stroke is currentColor, or the label's computed color.",
      "sources": [
        "https://carbondesignsystem.com/elements/icons/usage/",
        "https://fluent2.microsoft.design/iconography"
      ],
      "prov": "published"
    },
    {
      "id": "fill-is-state",
      "rule": "Filled means selected. Outline means everything else.",
      "value": "In a nav, tab bar or toggle group, only the current item is filled.",
      "check": "At most one filled icon per single-select group, on the element with aria-current or aria-selected.",
      "sources": [
        "https://fluent2.microsoft.design/iconography",
        "https://developer.apple.com/design/human-interface-guidelines/sf-symbols",
        "https://developers.google.com/fonts/docs/material_symbols"
      ],
      "prov": "published"
    },
    {
      "id": "target",
      "rule": "Make every icon button at least 44 × 44px to tap.",
      "value": "44px hit area (Apple, IBM, Lucide; WCAG AAA). 24px is the legal floor (WCAG 2.5.8 AA). The glyph can stay 20–24px.",
      "check": "The nearest button or link around an icon measures at least 44 × 44.",
      "sources": [
        "https://developer.apple.com/design/human-interface-guidelines/buttons",
        "https://www.w3.org/TR/WCAG22/"
      ],
      "prov": "published"
    },
    {
      "id": "label",
      "rule": "Hide icons that repeat their label; name icon-only buttons.",
      "value": "Beside text: aria-hidden=\"true\". Alone in a button: aria-label on the button.",
      "check": "An svg beside text has aria-hidden; a button with only an svg has a non-empty accessible name.",
      "sources": [
        "https://lucide.dev/how-to/accessibility",
        "https://primer.style/octicons/usage-guidelines/"
      ],
      "prov": "published"
    },
    {
      "id": "sparingly",
      "rule": "Use icons only where they add meaning.",
      "value": "Never the same icon on three or more siblings; one meaning per icon, one icon per meaning.",
      "check": "Fail when 3+ siblings share an identical icon; fail when one icon name sits beside two different labels.",
      "sources": [
        "https://lucide.dev/how-to/icon-guide",
        "https://atlassian.design/foundations/iconography",
        "https://www.ibm.com/design/language/iconography/ui-icons/usage/"
      ],
      "prov": "published"
    },
    {
      "id": "no-emoji",
      "rule": "No emoji standing in for icons.",
      "value": "Emoji are for what people type, not for the interface.",
      "check": "No \\p{Extended_Pictographic} in buttons, links, headings, list markers or icon slots.",
      "sources": [
        "https://primer.style/octicons/usage-guidelines/"
      ],
      "prov": "our reading",
      "why": "Primer reserves emoji for content people choose; we apply it to marketing pages."
    }
  ],
  "mistakes": [
    {
      "name": "Mixing sets",
      "what": "Heroicons in the nav, Lucide in the features, Font Awesome in the footer: strokes, caps and corners disagree.",
      "rule": "one-set"
    },
    {
      "name": "Emoji as icons",
      "what": "Multicolor, different on every phone, and blind to the brand's colors and weights.",
      "rule": "no-emoji"
    },
    {
      "name": "Icon soup",
      "what": "A check or sparkle on every bullet, adding nothing the words don't say.",
      "rule": "sparingly"
    },
    {
      "name": "Stroke that fights the type",
      "what": "A 2px stroke beside light type, or a 24px icon blown up to 64px with a 5px stroke.",
      "rule": "stroke-by-size"
    },
    {
      "name": "Fill as decoration",
      "what": "Filled icons used for emphasis, so nothing reads as selected.",
      "rule": "fill-is-state"
    },
    {
      "name": "Tiny targets",
      "what": "The 20px glyph is the whole button, sitting low on the baseline.",
      "rule": "target"
    }
  ],
  "concepts": [
    "search",
    "arrow-right",
    "check",
    "close",
    "user",
    "calendar",
    "chart",
    "mail",
    "lock",
    "settings",
    "home",
    "heart",
    "bell",
    "download",
    "play",
    "spark"
  ],
  "sets": [
    {
      "id": "lucide",
      "name": "Lucide",
      "package": "lucide-static",
      "version": "1.64.0",
      "license": "ISC",
      "license_url": "https://github.com/lucide-icons/lucide/blob/main/LICENSE",
      "site": "https://lucide.dev",
      "canvas": 24,
      "drawn_as": "stroke",
      "styles": [
        {
          "id": "line",
          "label": "Line",
          "stroke_24": 2
        }
      ],
      "files": {
        "search": "search",
        "arrow-right": "arrow-right",
        "check": "check",
        "close": "x",
        "user": "user",
        "calendar": "calendar",
        "chart": "chart-column",
        "mail": "mail",
        "lock": "lock",
        "settings": "settings",
        "home": "house",
        "heart": "heart",
        "bell": "bell",
        "download": "download",
        "play": "play",
        "spark": "sparkles"
      }
    },
    {
      "id": "phosphor",
      "name": "Phosphor",
      "package": "@phosphor-icons/core",
      "version": "2.1.1",
      "license": "MIT",
      "license_url": "https://github.com/phosphor-icons/core/blob/main/LICENSE",
      "site": "https://phosphoricons.com",
      "canvas": 24,
      "drawn_as": "fill",
      "styles": [
        {
          "id": "thin",
          "label": "Thin",
          "stroke_24": 0.75
        },
        {
          "id": "light",
          "label": "Light",
          "stroke_24": 1.125
        },
        {
          "id": "regular",
          "label": "Regular",
          "stroke_24": 1.5
        },
        {
          "id": "bold",
          "label": "Bold",
          "stroke_24": 2.25
        },
        {
          "id": "fill",
          "label": "Fill",
          "stroke_24": null
        },
        {
          "id": "duotone",
          "label": "Duotone",
          "stroke_24": null
        }
      ],
      "files": {
        "search": "magnifying-glass",
        "arrow-right": "arrow-right",
        "check": "check",
        "close": "x",
        "user": "user",
        "calendar": "calendar",
        "chart": "chart-bar",
        "mail": "envelope",
        "lock": "lock",
        "settings": "gear",
        "home": "house",
        "heart": "heart",
        "bell": "bell",
        "download": "download",
        "play": "play",
        "spark": "sparkle"
      }
    },
    {
      "id": "tabler",
      "name": "Tabler",
      "package": "@tabler/icons",
      "version": "3.50.0",
      "license": "MIT",
      "license_url": "https://github.com/tabler/tabler-icons/blob/main/LICENSE",
      "site": "https://tabler.io/icons",
      "canvas": 24,
      "drawn_as": "stroke",
      "styles": [
        {
          "id": "outline",
          "label": "Outline",
          "stroke_24": 2
        }
      ],
      "files": {
        "search": "search",
        "arrow-right": "arrow-right",
        "check": "check",
        "close": "x",
        "user": "user",
        "calendar": "calendar",
        "chart": "chart-bar",
        "mail": "mail",
        "lock": "lock",
        "settings": "settings",
        "home": "home",
        "heart": "heart",
        "bell": "bell",
        "download": "download",
        "play": "player-play",
        "spark": "sparkles"
      }
    },
    {
      "id": "heroicons",
      "name": "Heroicons",
      "package": "heroicons",
      "version": "2.2.0",
      "license": "MIT",
      "license_url": "https://github.com/tailwindlabs/heroicons/blob/master/LICENSE",
      "site": "https://heroicons.com",
      "canvas": 24,
      "drawn_as": "stroke",
      "styles": [
        {
          "id": "outline",
          "label": "Outline",
          "stroke_24": 1.5
        },
        {
          "id": "solid",
          "label": "Solid",
          "stroke_24": 1.5
        }
      ],
      "files": {
        "search": "magnifying-glass",
        "arrow-right": "arrow-right",
        "check": "check",
        "close": "x-mark",
        "user": "user",
        "calendar": "calendar",
        "chart": "chart-bar",
        "mail": "envelope",
        "lock": "lock-closed",
        "settings": "cog-6-tooth",
        "home": "home",
        "heart": "heart",
        "bell": "bell",
        "download": "arrow-down-tray",
        "play": "play",
        "spark": "sparkles"
      }
    },
    {
      "id": "iconoir",
      "name": "Iconoir",
      "package": "iconoir",
      "version": "7.12.1",
      "license": "MIT",
      "license_url": "https://github.com/iconoir-icons/iconoir/blob/main/LICENSE",
      "site": "https://iconoir.com",
      "canvas": 24,
      "drawn_as": "stroke",
      "styles": [
        {
          "id": "regular",
          "label": "Regular",
          "stroke_24": 1.5
        }
      ],
      "files": {
        "search": "search",
        "arrow-right": "arrow-right",
        "check": "check",
        "close": "xmark",
        "user": "user",
        "calendar": "calendar",
        "chart": "stats-report",
        "mail": "mail",
        "lock": "lock",
        "settings": "settings",
        "home": "home",
        "heart": "heart",
        "bell": "bell",
        "download": "download",
        "play": "play",
        "spark": "sparks"
      }
    },
    {
      "id": "remix",
      "name": "Remix Icon",
      "package": "remixicon",
      "version": "4.9.1",
      "license": "Apache-2.0",
      "license_url": "https://github.com/Remix-Design/RemixIcon/blob/master/License",
      "site": "https://remixicon.com",
      "canvas": 24,
      "drawn_as": "fill",
      "styles": [
        {
          "id": "line",
          "label": "Line",
          "stroke_24": null
        },
        {
          "id": "fill",
          "label": "Fill",
          "stroke_24": null
        }
      ],
      "files": {
        "search": "search",
        "arrow-right": "arrow-right",
        "check": "check",
        "close": "close",
        "user": "user",
        "calendar": "calendar",
        "chart": "bar-chart",
        "mail": "mail",
        "lock": "lock",
        "settings": "settings-3",
        "home": "home",
        "heart": "heart",
        "bell": "notification-3",
        "download": "download",
        "play": "play",
        "spark": "sparkling"
      }
    },
    {
      "id": "material",
      "name": "Material Symbols",
      "package": "@material-symbols/svg-400",
      "version": "0.48.2",
      "license": "Apache-2.0",
      "license_url": "https://github.com/google/material-design-icons/blob/master/LICENSE",
      "site": "https://fonts.google.com/icons",
      "canvas": 24,
      "drawn_as": "fill",
      "styles": [
        {
          "id": "outlined",
          "label": "Outlined",
          "stroke_24": null
        },
        {
          "id": "rounded",
          "label": "Rounded",
          "stroke_24": null
        },
        {
          "id": "filled",
          "label": "Filled",
          "stroke_24": null
        }
      ],
      "files": {
        "search": "search",
        "arrow-right": "arrow_forward",
        "check": "check",
        "close": "close",
        "user": "person",
        "calendar": "calendar_month",
        "chart": "bar_chart",
        "mail": "mail",
        "lock": "lock",
        "settings": "settings",
        "home": "home",
        "heart": "favorite",
        "bell": "notifications",
        "download": "download",
        "play": "play_arrow",
        "spark": "stars"
      }
    }
  ],
  "gaps": [
    "No system publishes the gap between an icon and its label as a number; ours is 0.5em, our recipe.",
    "Material 3's icon pages render client-side and couldn't be read; Material values here are from Material 2 (2019) and the Material Symbols developer guide.",
    "Remix and Iconoir publish no craft guide; their strokes are measured from their files."
  ]
}