@ekanos/cli 0.3.6 → 0.4.0

package/templates/skills/polish-widgets/references/patterns.md

@@ -30,9 +30,12 @@ attention?". Values styled like labels, metadata styled like values.
 
 ```tsx
 // AFTER — name leads, value anchors right, metadata recedes
-<div className="divide-border divide-y">
+<div className="divide-border/50 divide-y">
   {invoices.map((inv) => (
-    <div key={inv.id} className="flex items-center gap-3 px-4 py-3">
+    <div
+      key={inv.id}
+      className="hover:bg-accent/50 flex items-center gap-3 px-5 py-3"
+    >
       <div className="min-w-0 flex-1">
         <p className="truncate text-base font-medium">{inv.customer}</p>
         <p className="text-muted-foreground text-sm">
@@ -49,7 +52,10 @@ attention?". Values styled like labels, metadata styled like values.
 
 Rules at work: `min-w-0 flex-1` + `truncate` so long names never push the
 value out; `shrink-0` + `tabular-nums` so amounts hold a column; rows own
-their padding (`px-4 py-3`), the container owns none.
+their padding (`px-5 py-3`), the container owns none — so the hover band and
+the separators bleed to the card's edge. The hover is a flat
+`hover:bg-accent/50` band; a `rounded-lg` pill with side padding is the drift
+this pattern exists to prevent.
 
 ## 2. Bare stat grid → hero KPI with supporting stats
 
@@ -67,21 +73,28 @@ doing?") has no answer — every number claims the same importance.
 ```
 
 ```tsx
-// AFTER — one hero, a delta, the rest demoted to a footer strip
-<div className="flex flex-1 flex-col items-center justify-center px-4 py-6">
-  <span className="text-muted-foreground text-sm">Revenue this month</span>
-  <span className="text-3xl font-semibold tracking-tight tabular-nums">
-    {formatCurrency(revenue)}
-  </span>
-  <span
-    className={cn(
-      'mt-1 text-sm font-medium',
-      delta >= 0 ? 'text-success-strong' : 'text-destructive',
-    )}
-  >
-    {delta >= 0 ? '+' : ''}
-    {delta.toFixed(1)}% vs last month
-  </span>
+// AFTER — one hero as a Stat, the rest demoted to a footer strip
+import {
+  Stat,
+  StatChange,
+  StatDetail,
+  StatFigure,
+  StatLabel,
+  StatValue,
+} from '@ekanos/ui/stat';
+
+<div className="px-5 py-5">
+  <Stat>
+    <StatLabel>Revenue this month</StatLabel>
+    <StatFigure>
+      <StatValue>{formatCurrency(revenue)}</StatValue>
+      <StatChange tone={delta >= 0 ? 'positive' : 'negative'}>
+        {delta >= 0 ? '+' : ''}
+        {delta.toFixed(1)}%
+      </StatChange>
+    </StatFigure>
+    <StatDetail>vs. last month</StatDetail>
+  </Stat>
 </div>
 
 <div className="flex shrink-0 items-center border-t">
@@ -93,59 +106,72 @@ doing?") has no answer — every number claims the same importance.
     <Fragment key={stat.label}>
       {i > 0 && <div className="bg-border h-8 w-px" />}
       <div className="flex flex-1 flex-col items-center py-3">
-        <span className="text-lg font-semibold tabular-nums">{stat.value}</span>
-        <span className="text-muted-foreground text-xs">{stat.label}</span>
+        <span className="text-base font-semibold tabular-nums">
+          {stat.value}
+        </span>
+        <span className="text-muted-foreground text-sm">{stat.label}</span>
       </div>
     </Fragment>
   ))}
 </div>
 ```
 
-(`cn` from `@ekanos/ui/utils`.) Pick the hero by the interview's SEE-outcome,
-not by which number is largest. One `text-3xl` element per widget — two heroes
-is zero heroes.
+`Stat` owns the sizes — the heading face, `text-2xl`, `tracking-tight`,
+`tabular-nums`, and the arrow glyph that pairs with `StatChange`'s color so
+the tone never rides on hue alone. Don't override them, and don't rebuild
+them by hand: a Source that swaps typefaces carries the component, not your
+spans.
+
+Pick the hero by the interview's SEE-outcome, not by which number is largest.
+One `Stat` per widget is the hero; a row of up to three `Stat`s is fine —
+they are sized not to compete. A second `StatValue`-sized figure in the body
+is two heroes, which is zero heroes.
 
-## 3. Unstyled status → semantic badge or dot
+## 3. Unstyled status → `StatusBadge`
 
-**Failure:** status as bare text, or hardcoded palette (`bg-green-500`) that
-breaks in dark mode and off-brand tenants.
+**Failure:** status as bare text, a hardcoded palette (`bg-green-500`) that
+breaks in dark mode and off-brand tenants, or a tone passed to `Badge`'s
+`variant` — which no longer exists.
 
 ```tsx
 // BEFORE
 <span className="text-xs">{sub.status}</span>
 // or
 <span className="rounded bg-green-500 px-1 text-white">{sub.status}</span>
+// or, just as wrong today:
+<Badge variant="success">Active</Badge>
 ```
 
 ```tsx
-// AFTER — Badge variants carry the semantics; the map is the single source
-import { Badge } from '@ekanos/ui/badge';
+// AFTER — StatusBadge carries the tone; the map is the single source
+import { StatusBadge } from '@ekanos/ui/status-badge';
 
-const STATUS_VARIANT = {
+const STATUS_TONE = {
   active: 'success',
   trialing: 'info',
   past_due: 'warning',
   canceled: 'destructive',
 } as const;
 
-<Badge variant={STATUS_VARIANT[sub.status] ?? 'outline'}>
+<StatusBadge tone={STATUS_TONE[sub.status] ?? 'neutral'}>
   {STATUS_LABEL[sub.status] ?? sub.status}
-</Badge>;
+</StatusBadge>;
 ```
 
-When a badge is too loud (dense lists), use a dot plus muted text instead:
+`StatusBadge` renders a neutral outlined pill with a `size-2` dot in the
+tone: the words carry the meaning and the dot confirms it, so a long list
+stays calm and a color-blind reader loses nothing. That is why it works in a
+dense list and a tinted pill does not — there is no quieter variant to reach
+for.
 
-```tsx
-<span
-  className={cn(
-    'h-2.5 w-2.5 shrink-0 rounded-full',
-    sub.status === 'active' ? 'bg-success' : 'bg-muted-foreground/40',
-  )}
-/>
-<span className="text-muted-foreground text-sm">{STATUS_LABEL[sub.status]}</span>
-```
+`Badge` is for counts, categories and tags only. **It has no tone variants**:
+`success`, `warning` and `info` were deleted from the host kit on 2026-10-06.
+`@ekanos/ui`'s `Badge` still accepts one, for integrations published before
+that date, and silently renders the `StatusBadge` pill instead — so writing
+one today is dead code that ships a pill you did not ask for, and the host's
+own lint rejects it outright.
 
-One status treatment per row. A row with a colored badge AND a colored icon
+One status treatment per row. A row with a colored pill AND a colored icon
 AND colored money is signalling nothing.
 
 ## 4. Cramped card → sizing floors applied
@@ -166,10 +192,13 @@ is not information-rich; it is unreadable.
 ```
 
 ```tsx
-// AFTER — floors: rows px-4 py-3, icons h-5 w-5, body text-sm+
-<div className="divide-border divide-y">
+// AFTER — floors: rows px-5 py-3, icons h-5 w-5, body text-base
+<div className="divide-border/50 divide-y">
   {events.slice(0, 6).map((e) => (
-    <div key={e.id} className="flex items-start gap-3 px-4 py-3">
+    <div
+      key={e.id}
+      className="hover:bg-accent/50 flex items-start gap-3 px-5 py-3"
+    >
       <span className="bg-muted text-muted-foreground shrink-0 rounded-full p-2">
         <Icon name={eventIcon(e.type)} className="h-5 w-5" />
       </span>
@@ -207,7 +236,7 @@ import { Button } from '@ekanos/ui/button';
     <div className="divide-border divide-y">{rows}</div>
   </div>
   {items.length > 7 && (
-    <div className="shrink-0 border-t px-4 py-2">
+    <div className="shrink-0 border-t px-5 py-2">
       <Button variant="ghost" size="sm" className="text-muted-foreground">
         View all {items.length}
       </Button>
@@ -252,22 +281,25 @@ import {
 The one visible action should be the urgent one; if no action is urgent, all
 of them belong in the menu.
 
-## 7. Blank empty state → designed empty state
+## 7. Blank empty state → `Widget.Empty`
 
 **Failure:** an empty array renders an empty card, indistinguishable from a
 bug. Empty is a state you design, distinct from error.
 
+The SDK owns this state — don't hand-roll it. `Widget.Empty` is positive by
+default ("You're all caught up") and neutral only when nothing good can be
+said, and it matches every other widget on the board:
+
 ```tsx
-// AFTER — icon, one sentence of what appears here, what action produces it
-<div className="flex flex-1 flex-col items-center justify-center gap-3 p-8 text-center">
-  <div className="bg-muted flex h-16 w-16 items-center justify-center rounded-full">
-    <Icon name="fa-light fa-inbox" className="text-muted-foreground h-8 w-8" />
-  </div>
-  <p className="text-base font-medium">No invoices yet</p>
-  <p className="text-muted-foreground max-w-xs text-sm">
-    Invoices appear here as soon as your first one is issued.
-  </p>
-</div>
+// AFTER — the SDK's empty state, one sentence of what appears here
+<Widget.Empty
+  icon="fa-light fa-inbox"
+  title="No invoices yet"
+  description="Invoices appear here as soon as your first one is issued."
+/>
 ```
 
-No CTA unless there is a real action the user can take from the dashboard.
+Check the SDK README §`components.widgets` for the exact prop names in your
+installed version. No CTA unless there is a real action the user can take
+from the dashboard — and "not connected" is a different state again
+(`Widget.Inactive reason="not-connected"`), never a lock screen.

package/templates/src/integration.ts.tmpl

@@ -10,16 +10,60 @@
  */
 import { createElement } from 'react';
 
+import { Widget } from '@ekanos/sdk/components';
 import { defineIntegration } from '@ekanos/sdk/integration';
+import {
+  Stat,
+  StatDetail,
+  StatFigure,
+  StatLabel,
+  StatValue,
+} from '@ekanos/ui/stat';
 
-// A minimal dashboard widget. This starter uses React.createElement so it can
-// live in a .ts file; move it to its own .tsx file and reach for the Widget.*
-// compound API from '@ekanos/sdk/components' when you build something real.
+// A minimal dashboard widget, built from the Widget.* compound API and the
+// host's own `Stat`. Two rules this starter encodes, because they are the two
+// partners get wrong most often:
+//
+//   * Never a hand-sized figure. `Stat` sets the label, the figure and the
+//     context line to the host's spec, so a Source that swaps typefaces or
+//     corners carries your widget with it.
+//   * Never an inline `style`. Everything is a Tailwind class on the host's
+//     semantic tokens; an inline style escapes the theme, dark mode and the
+//     Source's branding, and `ekanos validate` warns on it.
+//
+// This starter uses React.createElement so it can live in a .ts file. Move it
+// to its own .tsx file as soon as it grows past this — `.claude/skills/
+// build-integration/references/widget-design.md` is the design guide.
 function HelloWidget() {
   return createElement(
-    'div',
-    { style: { padding: 16 } },
-    'Hello from __DISPLAY_NAME__',
+    Widget.DataState,
+    null,
+    createElement(
+      Widget.Card,
+      null,
+      createElement(Widget.Header, { context: 'Since you scaffolded this' }),
+      createElement(
+        Widget.Active,
+        null,
+        createElement(
+          Widget.Body,
+          null,
+          createElement(
+            Stat,
+            null,
+            createElement(StatLabel, null, 'Greetings sent'),
+            createElement(
+              StatFigure,
+              null,
+              createElement(StatValue, null, '1'),
+            ),
+            createElement(StatDetail, null, 'Hello from __DISPLAY_NAME__'),
+          ),
+        ),
+      ),
+      createElement(Widget.Loading, { variant: 'stat' }),
+      createElement(Widget.Error, null),
+    ),
   );
 }