{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"featured-icon","title":"Featured Icon","description":"A glyph in a tinted circle, a solid or raised square or with pulsing rings, to lead a message, a dialog or an empty state. Search terms: icon container, icon badge, status icon, pulse.","dependencies":[],"registryDependencies":["@siteplane/base"],"files":[{"path":"packages/ui/src/components/featured-icon/featured-icon.tsx","content":"\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"../../system/utils/cn\";\nimport { slotClass } from \"../../system/utils/slot-class\";\n\nimport \"./featured-icon.css\";\n\n/**\n * The color of a featured icon: the kit's status values, `accent` and\n * `neutral`.\n */\nexport type FeaturedIconTone =\n  \"neutral\" | \"accent\" | \"error\" | \"warning\" | \"success\";\n\n/**\n * How the glyph is set. `outline` is the bare glyph whose two rings exist\n * only as the pulse (rulebook I6), the lead of a Notification. `light` is a\n * circle in the tone's tint. `gradient` is a disc in the tone's solid fill\n * inside a halo of its tint that fades out downward. `dark` is a square in the\n * solid fill. `modern` is a square with the raised surface of the default\n * Button and the glyph in the tone's text color. `modern-neue` is a square\n * that holds a raised tile 4 px inside its edge.\n */\nexport type FeaturedIconVariant =\n  \"dark\" | \"gradient\" | \"light\" | \"modern\" | \"modern-neue\" | \"outline\";\n\n/**\n * The sizes: sm, md, lg and xl are 32, 40, 48 and 56 px with a 16,\n * 20, 24 and 28 px glyph. Without a size the icon is 36 px with an 18 px\n * glyph, the lead column of a Notification (rulebook I6, I9), unless a surface\n * around it sets the size of its featured icons (FeaturedIconSizeScope).\n */\nexport type FeaturedIconSize = \"sm\" | \"md\" | \"lg\" | \"xl\";\n\nconst FeaturedIconSizeContext = React.createContext<\n  FeaturedIconSize | undefined\n>(undefined);\n\n/**\n * Sets the size of the featured icons inside it that name none. A surface that\n * steps its featured icon with its own scale wraps its media in it, as Empty\n * does: xl in an lg Empty, lg in md and sm. A `size` of the icon itself wins.\n * Context only: it draws nothing.\n */\nexport function FeaturedIconSizeScope({\n  children,\n  size,\n}: {\n  children: React.ReactNode;\n  size: FeaturedIconSize | undefined;\n}): React.ReactElement {\n  return (\n    <FeaturedIconSizeContext.Provider value={size}>\n      {children}\n    </FeaturedIconSizeContext.Provider>\n  );\n}\n\nexport type FeaturedIconProps = Omit<\n  React.ComponentProps<\"span\">,\n  \"children\"\n> & {\n  /** The glyph, such as an icon component's svg, sized by the icon. */\n  children?: React.ReactNode;\n  /**\n   * Whether the rings of an `outline` icon pulse: they keep traveling outward\n   * from the glyph as they fade. On by default. The rings exist only as the\n   * pulse, so `false` and reduced motion show the glyph alone. The other\n   * variants have no rings.\n   */\n  pulse?: boolean | undefined;\n  /**\n   * sm, md, lg or xl; without one, 36 px with an 18 px glyph, or the size that\n   * the surface around the icon sets for its featured icons, as Empty does.\n   */\n  size?: FeaturedIconSize | undefined;\n  /** The color, `neutral` by default. */\n  tone?: FeaturedIconTone | undefined;\n  /** How the glyph is set; `outline` by default. */\n  variant?: FeaturedIconVariant | undefined;\n};\n\n/**\n * A glyph set in a box to lead a message, a dialog or an empty state. The\n * box, the glyph and every variant's fill and edges belong to\n * featured-icon.css, which takes them from the kit's tokens: the status tints\n * and fills that the Badge and the solid Button use, and the raised surface\n * of the default Button. The icon is decoration and hidden from assistive\n * technology; the text beside it says what it means.\n *\n * The `outline` icon, the default, pulses for as long as it is shown: two\n * rings keep traveling outward from the glyph as they fade, a new ring every\n * 2 s. They are drawn around the box without taking layout space, so text\n * beside it keeps its column. There is no still ring: with `pulse={false}`,\n * with reduced motion and after the last wave of a limited pulse, the glyph\n * stands alone in its box.\n */\nexport function FeaturedIcon({\n  children,\n  className,\n  pulse = true,\n  size,\n  tone = \"neutral\",\n  variant = \"outline\",\n  ...props\n}: FeaturedIconProps): React.ReactElement {\n  const scopedSize = React.useContext(FeaturedIconSizeContext);\n  return (\n    <span\n      aria-hidden=\"true\"\n      data-slot=\"featured-icon\"\n      data-tone={tone}\n      data-variant={variant}\n      data-size={size ?? scopedSize}\n      data-pulse={variant === \"outline\" && pulse ? \"\" : undefined}\n      {...props}\n      className={cn(slotClass(\"featured-icon\", props), className)}\n    >\n      {children}\n    </span>\n  );\n}\n","type":"registry:ui","target":"~/src/siteplane/components/featured-icon/featured-icon.tsx"},{"path":"packages/ui/src/components/featured-icon/featured-icon.css","content":"@layer theme, base, components, siteplane, utilities;\n\n@layer siteplane {\n  /* A featured icon is a glyph centred in a box\n   * (Lukas, 30 October 2026). Without a size the box is 36 px with an 18 px\n   * glyph, the lead column of a Notification (rulebook I6, I9); sm, md, lg and\n   * xl are 32, 40, 48 and 56 px with a 16, 20, 24 and 28 px glyph.\n   * The box, the glyph and the outline's colour are defaults without\n   * specificity, which the sizes, tones and variants below refine (P6). The\n   * variables carry each size's corners: the square of dark and modern, the\n   * outer square of modern-neue, and the disc and glyph of gradient. */\n  :where(.sp-featured-icon) {\n    --sp-featured-icon-box: calc(var(--sp-rw-space) * 9);\n    --sp-featured-icon-glyph: calc(var(--sp-rw-space) * 4.5);\n    --sp-featured-icon-radius: var(--sp-rw-radius-control);\n    --sp-featured-icon-neue-radius: var(--radius-lg);\n    --sp-featured-icon-disc: calc(var(--sp-rw-space) * 6.5);\n    --sp-featured-icon-disc-glyph: var(--sp-rw-space-4);\n    --sp-featured-icon-edge: color-mix(\n      in oklch,\n      var(--sp-featured-icon-fill) 24%,\n      transparent\n    );\n\n    position: relative;\n    display: flex;\n    flex-shrink: 0;\n    align-items: center;\n    justify-content: center;\n    width: var(--sp-featured-icon-box);\n    height: var(--sp-featured-icon-box);\n    color: var(--sp-featured-icon-outline);\n  }\n\n  :where(.sp-featured-icon > svg) {\n    flex-shrink: 0;\n    width: var(--sp-featured-icon-glyph);\n    height: var(--sp-featured-icon-glyph);\n  }\n\n  :root .sp-featured-icon[data-size=\"sm\"] {\n    --sp-featured-icon-box: var(--sp-rw-space-8);\n    --sp-featured-icon-glyph: var(--sp-rw-space-4);\n    --sp-featured-icon-radius: var(--sp-rw-radius-sm);\n    --sp-featured-icon-neue-radius: var(--sp-rw-radius-control);\n    --sp-featured-icon-disc: var(--sp-rw-space-6);\n  }\n\n  :root .sp-featured-icon[data-size=\"md\"] {\n    --sp-featured-icon-box: var(--sp-rw-space-10);\n    --sp-featured-icon-glyph: var(--sp-rw-space-5);\n    --sp-featured-icon-radius: var(--sp-rw-radius-control);\n    --sp-featured-icon-neue-radius: var(--radius-lg);\n    --sp-featured-icon-disc: var(--sp-rw-space-7);\n  }\n\n  :root .sp-featured-icon[data-size=\"lg\"] {\n    --sp-featured-icon-box: var(--sp-rw-space-12);\n    --sp-featured-icon-glyph: var(--sp-rw-space-6);\n    --sp-featured-icon-radius: var(--radius-lg);\n    --sp-featured-icon-neue-radius: var(--sp-rw-radius-surface);\n    --sp-featured-icon-disc: var(--sp-rw-space-8);\n    --sp-featured-icon-disc-glyph: var(--sp-rw-space-5);\n  }\n\n  :root .sp-featured-icon[data-size=\"xl\"] {\n    --sp-featured-icon-box: calc(var(--sp-rw-space) * 14);\n    --sp-featured-icon-glyph: var(--sp-rw-space-7);\n    --sp-featured-icon-radius: var(--sp-rw-radius-surface);\n    --sp-featured-icon-neue-radius: var(--radius-xl);\n    --sp-featured-icon-disc: var(--sp-rw-space-10);\n    --sp-featured-icon-disc-glyph: var(--sp-rw-space-5);\n  }\n\n  /* The tones. The outline is a bare status glyph, so it takes the tone of\n   * its status dot in both themes, as every status glyph does (rulebook C4,\n   * Lukas, 7 November 2026, as coss): the success and warning dots, the error\n   * fill and the accent fill. The other variants take the kit's status\n   * tokens: the tint and its text colour of the Badge's status variants, and\n   * the solid fill with the text that reads on it of the solid Button and\n   * Badge (inverse for neutral). */\n  :root .sp-featured-icon[data-tone=\"neutral\"] {\n    --sp-featured-icon-outline: var(--sp-semantic-color-muted-foreground);\n    --sp-featured-icon-ink: var(--sp-rw-fg-secondary);\n    --sp-featured-icon-tint: var(--sp-rw-bg-muted);\n    --sp-featured-icon-fill: var(--sp-rw-bg-inverse);\n    --sp-featured-icon-on-fill: var(--sp-rw-fg-inverse);\n  }\n\n  :root .sp-featured-icon[data-tone=\"accent\"] {\n    --sp-featured-icon-outline: var(--sp-rw-bg-accent);\n    --sp-featured-icon-ink: var(--sp-rw-fg-accent);\n    --sp-featured-icon-tint: var(--sp-rw-bg-accent-translucent);\n    --sp-featured-icon-fill: var(--sp-rw-bg-accent);\n    --sp-featured-icon-on-fill: var(--sp-rw-fg-on-accent);\n  }\n\n  :root .sp-featured-icon[data-tone=\"success\"] {\n    --sp-featured-icon-outline: var(--sp-semantic-color-success);\n    --sp-featured-icon-ink: var(--sp-rw-fg-positive);\n    --sp-featured-icon-tint: var(--sp-rw-bg-positive-translucent);\n    --sp-featured-icon-fill: var(--sp-rw-bg-positive);\n    --sp-featured-icon-on-fill: var(--sp-rw-fg-emphasis);\n  }\n\n  :root .sp-featured-icon[data-tone=\"warning\"] {\n    --sp-featured-icon-outline: var(--sp-semantic-color-warning);\n    --sp-featured-icon-ink: var(--sp-rw-fg-attention);\n    --sp-featured-icon-tint: var(--sp-rw-bg-attention-translucent);\n    --sp-featured-icon-fill: var(--sp-rw-bg-attention);\n    --sp-featured-icon-on-fill: var(--sp-rw-fg-emphasis);\n  }\n\n  :root .sp-featured-icon[data-tone=\"error\"] {\n    --sp-featured-icon-outline: var(--sp-semantic-color-destructive);\n    --sp-featured-icon-ink: var(--sp-rw-fg-destructive);\n    --sp-featured-icon-tint: var(--sp-rw-bg-destructive-translucent);\n    --sp-featured-icon-fill: var(--sp-rw-bg-destructive);\n    --sp-featured-icon-on-fill: var(--sp-rw-fg-emphasis);\n  }\n\n  /* Light: a circle in the tone's tint, the glyph in its text colour. */\n  :root .sp-featured-icon[data-variant=\"light\"] {\n    border-radius: var(--sp-rw-radius-full);\n    background: var(--sp-featured-icon-tint);\n    color: var(--sp-featured-icon-ink);\n  }\n\n  /* Gradient: a disc in the tone's solid fill, the glyph in the text that\n   * reads on it, inside a halo of the tint whose hairline fades out downward.\n   * Both layers lie under the glyph. */\n  :root .sp-featured-icon[data-variant=\"gradient\"] {\n    isolation: isolate;\n    border-radius: var(--sp-rw-radius-full);\n    color: var(--sp-featured-icon-on-fill);\n  }\n\n  :root .sp-featured-icon[data-variant=\"gradient\"]::before {\n    position: absolute;\n    z-index: -1;\n    inset: 0;\n    border: var(--sp-rw-border-default) solid var(--sp-featured-icon-edge);\n    border-radius: inherit;\n    background: var(--sp-featured-icon-tint);\n    content: \"\";\n    -webkit-mask-image: linear-gradient(to bottom, black, transparent);\n    mask-image: linear-gradient(to bottom, black, transparent);\n  }\n\n  :root .sp-featured-icon[data-variant=\"gradient\"]::after {\n    position: absolute;\n    z-index: -1;\n    width: var(--sp-featured-icon-disc);\n    height: var(--sp-featured-icon-disc);\n    border-radius: var(--sp-rw-radius-full);\n    background: var(--sp-featured-icon-fill);\n    content: \"\";\n  }\n\n  :root .sp-featured-icon[data-variant=\"gradient\"] > svg {\n    width: var(--sp-featured-icon-disc-glyph);\n    height: var(--sp-featured-icon-disc-glyph);\n  }\n\n  /* Dark: a square in the tone's solid fill with the glyph in the text that\n   * reads on it, raised by the control's depth, with a hairline of that text\n   * colour one hairline inside its edge that fades out downward. */\n  :root .sp-featured-icon[data-variant=\"dark\"] {\n    isolation: isolate;\n    border-radius: var(--sp-featured-icon-radius);\n    background: var(--sp-featured-icon-fill);\n    box-shadow: var(--sp-rw-control-depth);\n    color: var(--sp-featured-icon-on-fill);\n  }\n\n  :root .sp-featured-icon[data-variant=\"dark\"]::before {\n    position: absolute;\n    z-index: -1;\n    inset: var(--sp-rw-border-default);\n    border: var(--sp-rw-border-default) solid\n      color-mix(in oklch, var(--sp-featured-icon-on-fill) 12%, transparent);\n    border-radius: calc(\n      var(--sp-featured-icon-radius) - var(--sp-rw-border-default)\n    );\n    content: \"\";\n    -webkit-mask-image: linear-gradient(to bottom, black, transparent);\n    mask-image: linear-gradient(to bottom, black, transparent);\n  }\n\n  /* Modern: the raised tile, the default Button's tertiary fill and dome with\n   * the tile's edge, which reads evenly on all four sides, its bevel and the\n   * control's depth (--sp-rw-tile-shadow), and the glyph in the tone's text\n   * colour. The Button's own shadow covers its rim at the top and the bottom,\n   * which on a square of 32 to 56 px read as a missing edge (Lukas, 2\n   * November 2026). */\n  :root .sp-featured-icon[data-variant=\"modern\"] {\n    border-radius: var(--sp-featured-icon-radius);\n    background: var(--sp-rw-control-dome), var(--sp-rw-bg-tertiary);\n    box-shadow: var(--sp-rw-tile-shadow);\n    color: var(--sp-featured-icon-ink);\n  }\n\n  /* Modern neue: a square of the tertiary fill with the outline rim, a frame\n   * that holds the raised tile 4 px inside its edge, concentric with it: the\n   * tile's edge and bevel, lifted by three layers of shadow that fall on the\n   * frame (--sp-rw-tile-raised-shadow), so the two edges read as a tile in its\n   * frame rather than as a double line (Lukas, 2 November 2026). */\n  :root .sp-featured-icon[data-variant=\"modern-neue\"] {\n    isolation: isolate;\n    border-radius: var(--sp-featured-icon-neue-radius);\n    background: var(--sp-rw-bg-tertiary);\n    box-shadow: var(--sp-rw-outline-rim);\n    color: var(--sp-featured-icon-ink);\n  }\n\n  :root .sp-featured-icon[data-variant=\"modern-neue\"]::before {\n    position: absolute;\n    z-index: -1;\n    inset: var(--sp-rw-space-1);\n    border-radius: calc(\n      var(--sp-featured-icon-neue-radius) - var(--sp-rw-space-1)\n    );\n    background: var(--sp-rw-control-dome), var(--sp-rw-bg-tertiary);\n    box-shadow: var(--sp-rw-tile-raised-shadow);\n    content: \"\";\n  }\n\n  /* Outline: the glyph alone in its box, in the outline colour above. Its two\n   * rings exist only as the pulse (rulebook I6, I1, M1, M2, M5): two identical\n   * rings in the tone colour, drawn by the box's ::before and ::after, travel\n   * outwards from the glyph and fade. A ring is a circle of seven ninths of the\n   * box, 28 px in the 36 px box; it leaves at three quarters of that, 21 px,\n   * just outside the glyph, and is gone at --motion-ring-pulse-scale (about\n   * 43 px). In a loop of --motion-duration-ring-pulse (4 s), a ring travels at\n   * an even pace for the first 80% (3.2 s), reaches --motion-ring-pulse-opacity\n   * (0.24 of the tone) a tenth of the way out and fades from there, then rests,\n   * faded, for the last 20% (0.8 s). The ::after runs half a loop behind, so\n   * both rings are under way from the first frame and a new ring leaves the\n   * glyph every half loop (2.0 s). A ring travels longer than that, so the next\n   * one leaves before it has faded: at least one ring is always in flight.\n   *\n   * Every outline icon pulses for as long as it is shown, in a NotificationList\n   * and a toast stack too: --motion-ring-pulse-count is infinite. A ring's own\n   * opacity is 0, so it shows only while it travels. Without the pulse the\n   * glyph stands alone in its box, and nothing moves: `pulse={false}` and the\n   * other variants leave out data-pulse, which every ring rule needs; reduced\n   * motion stops the rings; and an app that sets the count to a number gets\n   * the glyph alone when the last wave ends. Only transform and opacity\n   * animate, timed by the motion tokens. */\n  .sp-featured-icon[data-pulse]::before,\n  .sp-featured-icon[data-pulse]::after {\n    content: \"\";\n    position: absolute;\n    inset: calc(var(--sp-featured-icon-box) / 9);\n    border: 2px solid currentColor;\n    border-radius: 9999px;\n    opacity: 0;\n    pointer-events: none;\n    animation: sp-featured-icon-ring-pulse var(--motion-duration-ring-pulse)\n      var(--motion-ease-linear) var(--motion-ring-pulse-count);\n  }\n\n  /* Half a loop behind, already under way when the icon appears. */\n  .sp-featured-icon[data-pulse]::after {\n    animation-delay: calc(var(--motion-duration-ring-pulse) / -2);\n  }\n\n  /* From just outside the glyph (21 px in the 36 px box) to about 43 px over\n   * the first 80% of the loop; brightest a tenth of the way out (8%), at\n   * --motion-ring-pulse-opacity, then the ring fades as it travels. It rests,\n   * faded, for the last 20%. */\n  @keyframes sp-featured-icon-ring-pulse {\n    from {\n      opacity: 0;\n      transform: scale(0.75);\n    }\n\n    8% {\n      opacity: var(--motion-ring-pulse-opacity);\n    }\n\n    80%,\n    to {\n      opacity: 0;\n      transform: scale(var(--motion-ring-pulse-scale));\n    }\n  }\n\n  /* Reduced motion stops the rings, so the glyph stands alone and nothing moves\n   * (M5): the document mode, the provider preset and the system setting. */\n  html[data-motion-reduce=\"true\"] .sp-featured-icon[data-pulse]::before,\n  html[data-motion-reduce=\"true\"] .sp-featured-icon[data-pulse]::after,\n  [data-sp-motion=\"reduced\"] .sp-featured-icon[data-pulse]::before,\n  [data-sp-motion=\"reduced\"] .sp-featured-icon[data-pulse]::after {\n    animation: none;\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    .sp-featured-icon[data-pulse]::before,\n    .sp-featured-icon[data-pulse]::after {\n      animation: none;\n    }\n  }\n}\n","type":"registry:ui","target":"~/src/siteplane/components/featured-icon/featured-icon.css"},{"path":"packages/ui/src/components/featured-icon/index.ts","content":"export * from \"./featured-icon\";\n","type":"registry:ui","target":"~/src/siteplane/components/featured-icon/index.ts"}],"type":"registry:ui","docs":"https://ui.siteplane.io/docs-markdown/components/featured-icon.md","categories":["Data display"],"meta":{"avoidWhen":["Avoid for an icon inside running text, a button or a menu row; use the icon on its own.","Avoid for a person or an organization; use Avatar."],"description":"A glyph in a tinted circle, a solid or raised square or with pulsing rings, to lead a message, a dialog or an empty state.","knownLimitations":["The icon is decoration and hidden from assistive technology; the text beside it carries the meaning.","The outline rings exist only while they pulse; with pulse={false} or reduced motion the glyph stands alone."],"providerNotes":["SiteplaneMotionProvider preset=\"reduced\" and the system setting stop the pulse of an outline icon and show its glyph alone."],"releaseStatus":"preview","searchTerms":["featured icon","icon container","icon badge","status icon","pulse"],"useWhen":["Use to lead a notification, a confirmation dialog, an empty state or a feature list with an icon in a status tone.","Use the outline variant where the icon should draw the eye to a new message, with its pulsing rings."]}}