Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */

export const docs = {
  name: 'IconButton',
  displayName: 'Icon Button',
  group: 'Button',
  category: 'Action',
  keywords: ['icon-button', 'icon', 'button', 'toolbar', 'action', 'compact'],

  props: [
    {
      name: 'label',
      type: 'string',
      description:
        'Accessible label. Used as aria-label (not rendered as visible text).',
      required: true,
    },
    {
      name: 'icon',
      type: 'ReactNode',
      description:
        'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
      required: true,
      slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
    },
    {
      name: 'variant',
      type: "\'primary\' | \'secondary\' | \'ghost\' | \'destructive\'",
      description: 'Visual style variant.',
      default: "\'secondary\'",
    },
    {
      name: 'size',
      type: "\'sm\' | \'md\' | \'lg\'",
      description: 'Size variant.',
      default: "\'md\'",
    },
    {
      name: 'elevation',
      type: "'none' | 'low' | 'med' | 'high'",
      description:
        'Resting shadow depth. The most common FAB shape is an icon-only button, so raise it with `low`/`med`/`high` for a floating action button. `none` is the default flat button.',
      default: "'none'",
    },
    {
      name: 'isLoading',
      type: 'boolean',
      description:
        'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
      default: 'false',
    },
    {
      name: 'isDisabled',
      type: 'boolean',
      description:
        'Disables the button. Uses aria-disabled instead of native disabled so the button stays focusable.',
      default: 'false',
    },
    {
      name: 'tooltip',
      type: 'string',
      description:
        "Tooltip text shown on hover and keyboard focus. It also describes the button, unless it repeats the button's accessible name.",
    },
    {
      name: 'onClick',
      type: '(e: MouseEvent) => void',
      description: 'Standard click handler.',
    },
    {
      name: 'clickAction',
      type: '(e: MouseEvent) => void | Promise<void>',
      description: 'Async click handler with automatic loading state.',
    },
    {
      name: 'isInterruptible',
      type: 'boolean',
      description:
        'Keep the button clickable while a clickAction is pending: the spinner and aria-busy still show, but the button is not disabled and the action is not deduped, so a re-click lands and interrupts the in-flight action with a fresh one. Use it for interruptible actions, not fire-once actions (submit, save, pay).',
      default: 'false',
    },
    {
      name: 'width',
      type: 'SizeValue',
      description:
        'Width of the button. Numbers are treated as pixels, strings are used as-is. Without it the button keeps its icon-only aspect, square by default; with it the button takes that width.',
    },
    {
      name: 'type',
      type: "'button' | 'submit' | 'reset'",
      description: 'HTML button type attribute.',
      default: "'button'",
    },
    {
      name: 'name',
      type: 'string',
      description: 'HTML name attribute for form submission.',
    },
    {
      name: 'value',
      type: 'string | number | readonly string[]',
      description: 'HTML value attribute for form submission.',
    },
    {
      name: 'form',
      type: 'string',
      description: 'Associates the button with a form element by ID.',
    },
    {
      name: 'href',
      type: 'string',
      description:
        'When provided, renders the button as a link element (<a> or custom link component). A disabled IconButton still renders a <button>.',
    },
    {
      name: 'as',
      type: 'ComponentType',
      description:
        'Custom link component to use when href is provided (e.g. Next.js Link).',
    },
    {
      name: 'target',
      type: 'string',
      description:
        'HTML target attribute when rendered as a link (e.g. "_blank").',
    },
    {
      name: 'rel',
      type: 'string',
      description:
        'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
    },
  ],

  usage: {
    description:
      'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
    accessibility: [
      {
        name: 'Essential icon or spinner arc',
        category: 'Color contrast',
        criterion: '1.4.11 Non-text Contrast',
        requirement: '3:1',
        states: ['Rest', 'Hover', 'Pointer down', 'Loading'],
        description:
          'IconButton has no visible label. Its icon must have at least 3:1 contrast with the button background in Rest, Hover, and Pointer down. The moving spinner arc must also meet 3:1 while loading.',
      },
      {
        name: 'Visible control boundary',
        category: 'Color contrast',
        criterion: '1.4.11 Non-text Contrast',
        requirement: '3:1 if needed',
        states: ['Rest'],
        description:
          'The button edge needs 3:1 contrast only when users need it to see the control.',
      },
      {
        name: 'Keyboard focus indicator',
        category: 'Color contrast',
        criterion: '1.4.11 Non-text Contrast',
        requirement: '3:1',
        states: ['Focus visible'],
        description:
          'The focus outline must have at least 3:1 contrast with the area around the button. Check the red outline on destructive buttons too.',
      },
      {
        name: 'Disabled appearance',
        category: 'Color contrast',
        criterion: '1.4.3 and 1.4.11 exceptions',
        requirement: 'Not required',
        states: ['Disabled'],
        description:
          'Disabled controls do not need to meet these contrast ratios.',
      },
    ],
    bestPractices: [
      {
        guidance: true,
        description:
          'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.',
      },
      {
        guidance: true,
        description:
          'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.',
      },
      {
        guidance: true,
        description:
          'Use ghost in toolbars and dense areas to reduce visual clutter.',
      },
      {
        guidance: false,
        description:
          "Use IconButton if the action isn't obvious from the icon alone; use Button with text.",
      },
      {
        guidance: false,
        description:
          'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
  description:
    'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
  usage: {
    description:
      'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
    bestPractices: [
      {
        guidance: true,
        description:
          'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.',
      },
      {
        guidance: true,
        description:
          'Add tooltip: even gear icon can mean Settings/Preferences/Configure.',
      },
      {
        guidance: true,
        description:
          'Use ghost in toolbars + dense areas to reduce visual clutter.',
      },
      {
        guidance: false,
        description:
          "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead.",
      },
      {
        guidance: false,
        description:
          'Skip tooltip: label only reaches screen readers; sighted users need hover hint.',
      },
    ],
  },
  propDescriptions: {
    label: 'accessible label; used as aria-label, not rendered as visible text',
    icon: 'icon element rendered inside button; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
    variant: 'visual style variant',
    size: 'size variant',
    elevation:
      'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
    isLoading:
      'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
    isDisabled: 'disables button; uses aria-disabled instead of native disabled',
    tooltip:
      'tooltip on hover + keyboard focus; also describes the button unless it repeats the accessible name',
    onClick: 'standard click handler',
    clickAction: 'async click handler w/ automatic loading state',
    isInterruptible:
      'keeps button clickable while clickAction pending; a re-click interrupts it. Not for fire-once actions (submit/save/pay)',
    width:
      'button width; numbers=pixels, strings=as-is; without it keeps the icon-only aspect (square by default)',
    type: 'HTML button type; defaults to "button"',
    name: 'HTML name for form submission',
    value: 'HTML value for form submission',
    form: 'associates button with form element by ID',
    href: 'renders as a link; a disabled IconButton stays a <button>',
    as: 'custom link component used with href',
    target: 'HTML target when rendered as a link',
    rel: 'HTML rel when rendered as a link',
  },
};