Widgets

A widget is the small, glanceable face of your app on someone’s home screen. There are three sizes and they are fixed, because every app’s widgets share one grid and a widget that sets its own height breaks the alignment of everything beside it.

The three sizes

The column pitch is 170 with a 20px gap, which is where the other numbers come from: 170 + 20 + 170 = 360. Large is square at 360, not 376, so that two stacked mediums line up with one large exactly.

Use the toolkit

It handles the sizes, the spacing and the tap targets, and it is what the gates check against.

npm install @clarittyai/widget-toolkit

Layout

• WidgetContainer, locks the widget to its size and clips overflow.
• WidgetHeader, the title row.
• WidgetList, WidgetMetric, WidgetStat, the three things a widget usually is.

Controls and marks

• WidgetButton, meets the 44px minimum tap target on its own.
• WidgetToggle, WidgetBadge, WidgetAvatar, WidgetAvatarGroup.
• widgetText, text styles that never fall below the 12px minimum.

import { WidgetContainer, WidgetHeader, WidgetMetric } from '@clarittyai/widget-toolkit';

export default function Widget({ data }) {
  return (
    <WidgetContainer size="small">
      <WidgetHeader title="Overdue" />
      <WidgetMetric value={data.count} label="invoices" />
    </WidgetContainer>
  );
}

Where the data comes from

The dashboard polls GET /api/widget about every 30 seconds and hands the result to your component. Keep the endpoint’s shape and the component in step. A widget that renders empty on the dashboard is nearly always this contract drifting.

The rules the gates enforce