@ekanos/cli 0.1.6 → 0.1.7

package/templates/skills/polish-widgets/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: polish-widgets
+description: Review-and-fix pass over existing widget styling. Use when the user asks to review widget styling, wants widgets or the marketplace tile to look better, says the tile design is bad or the widgets look plain/generic/flat, reports overflow or responsiveness problems, or before publishing as a final styling pass.
+---
+
+# Polish Widgets
+
+A widget that renders the right data can still be a bad widget: every row the
+same weight, no element answering the widget's question, a grid of identical
+stat chips. This skill is the fix pass — render each widget in the harness,
+find the worst offenses, fix them, show the user before and after. The
+creation-time design rules live in
+`../build-integration/references/widget-design.md`; this skill assumes they
+exist and enforces them on code already written.
+
+## The key question
+
+Every widget exists to answer 1–2 questions. Name the question FIRST. Its
+answer must be the most prominent element — size, weight, position — and
+everything else demotes to supporting context. If you cannot name the
+question, that is the finding: ask the user what the widget is for before
+touching its classes.
+
+| Widget type         | Key question                       | Most prominent element                                                      |
+| ------------------- | ---------------------------------- | --------------------------------------------------------------------------- |
+| KPI / stat          | "How are we doing?"                | The hero number: `text-3xl font-semibold tracking-tight tabular-nums`       |
+| List / feed         | "What needs my attention?"         | Item name `text-base font-medium` + its value, right-aligned `tabular-nums` |
+| Chart               | "Which way is it going?"           | The chart plus the current value; axes and legends muted                    |
+| Action card         | "What can I do here?"              | One clear CTA; supporting copy secondary                                    |
+| Status / connection | "Is it working? What's connected?" | Badge or status dot + the identity it describes                             |
+
+The most common failure is uniform weight: everything `text-sm`, values styled
+like their labels. Squint at the rendered widget — if nothing reads first,
+there is no hierarchy, and that fix comes before any padding nit.
+
+## Review procedure
+
+1. **Enumerate** the widgets from `components.widgets` in `src/integration.ts`
+   — id, name, component file. Review all of them unless the user scoped it.
+2. **Render**: `npx ekanos dev`, then the Widgets surface at
+   `http://localhost:3100/<slug>/widgets`. Drive the review from the dev
+   toolbar: Render state (loading / error / inactive / disabled / active),
+   Viewport presets (check sm, not just lg), Collapsed, Unhealthy, and the
+   theme toggle — dark mode is part of the review, not an extra.
+3. **Assess** each widget against the checklist below and write findings per
+   widget, worst-first. Missing hierarchy outranks spacing; a broken sm layout
+   outranks a badge color.
+4. **Fix** worst-first, one widget at a time. After each: `npx tsc --noEmit`,
+   re-render in the harness.
+5. **Show the user** before/after for each widget — screenshots or ask them to
+   look — and get their read before the next one. Never claim a widget looks
+   better without one of the two.
+
+## Checklist
+
+**Hierarchy**
+
+- The key question's answer is the visually dominant element
+- One prominent element per row; supporting info is `text-muted-foreground`
+- Hero/stat values match the recipe: `text-3xl font-semibold tracking-tight
+tabular-nums` (never below `text-2xl`, and never `text-sm` on a number
+  that matters)
+- List row titles `text-base font-medium`; subtitles `text-sm text-muted-foreground`
+- `text-xs` only on tertiary metadata (timestamps, header badge counts)
+
+**Tokens & color**
+
+- Semantic tokens only — no `bg-white`, `text-gray-500`, hex, raw palette shades
+- Primary accent on ≤10% of the widget; status through `Badge` variants
+  (`success` / `warning` / `info` / `destructive`) or a semantic status dot
+- No two colored elements competing in one row
+- Both themes checked with the toolbar toggle
+
+**Layout & overflow**
+
+- Lists cap at 5–7 visible items; more goes behind inner scroll
+  (`min-h-0 flex-1 overflow-y-auto` on the list, never the card) or "View all"
+- `truncate` + `min-w-0` on user-supplied strings; values `shrink-0` and right-aligned
+- The sm viewport holds: cut columns, keep meaning
+- Sizing floors hold: rows `px-4 py-3`+, list icons `h-5 w-5`+, gaps `gap-3`+,
+  body text `text-sm`+
+
+**States & numbers**
+
+- All four states render (the toolbar flips loading/error/inactive; empty needs
+  a data mock) and empty is a designed state, not a blank card
+- Digits that align use `tabular-nums`; money is right-aligned with fixed width
+
+The canonical fix for the flat-row failure, since it is the one you will apply
+most:
+
+```tsx
+// Before: three spans, one size, no first read
+<div className="flex justify-between text-sm">
+  <span>{item.name}</span>
+  <span>{item.amount}</span>
+</div>
+
+// After: name leads, value anchors, metadata recedes
+<div className="flex items-center gap-3 px-4 py-3">
+  <div className="min-w-0 flex-1">
+    <p className="truncate text-base font-medium">{item.name}</p>
+    <p className="text-muted-foreground text-sm">{item.detail}</p>
+  </div>
+  <span className="shrink-0 text-base font-semibold tabular-nums">
+    {formatCurrency(item.amount)}
+  </span>
+</div>
+```
+
+Full before→after gallery — hero KPI, status treatment, sizing floors, inner
+scroll, row actions, designed empty state — in `references/patterns.md`. Read
+it before rewriting any widget body.
+
+## The marketplace tile
+
+"The tile looks bad" is usually not a styling bug — it is missing branding.
+The tile is `components.marketplaceTile` in the definition, typically built on
+`BaseMarketplaceTile` from `@ekanos/sdk/components`, and it renders from the
+props you pass: `name`, `summary` (1–2 sentences shown on the card),
+`brandName`, `logoPath`, `categories`, `productColor`, `ctaText`. Omit
+`logoPath` and the card falls back to a single-letter monogram; omit `summary`
+and the body sits blank next to its neighbours. Check the props before
+touching CSS.
+
+Review it at `http://localhost:3100/<slug>/tile` — the harness renders it
+inside the real catalogue grid with two inert neighbour cards, which is the
+only honest test: does the title wrap at column width, does the summary clamp
+like the neighbours', is the card the same height? (Register the component as
+`tile:` in `harness.config.ts` if the surface says none is registered.) The
+harness also notes this surface is lightly used by the live marketplace today
+— keep it correct and branded, don't gold-plate it.
+
+## Reporting
+
+Finish with a per-widget summary: the key question you assigned it, the
+findings fixed (worst-first), anything deliberately left, and confirmation the
+user saw the result. Then run the standard gate: `npx tsc --noEmit` and
+`npx ekanos validate` clean.

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

@@ -0,0 +1,269 @@
+# Widget fix patterns — before → after
+
+Each pattern names the failure, then shows the smallest honest fix. All
+imports are `@ekanos/ui/*`; icons go through `@ekanos/ui/icon` (Font Awesome
+names — verify against the Free set). Everything sits inside the standard
+`Widget.Active` body from the SDK's compound API; these are the bodies, not
+the wrapper.
+
+## 1. Flat list row → row with a first read
+
+**Failure:** every field the same size, so nothing answers "what needs my
+attention?". Values styled like labels, metadata styled like values.
+
+```tsx
+// BEFORE — three spans, one weight
+{
+  invoices.map((inv) => (
+    <div key={inv.id} className="flex justify-between p-2 text-sm">
+      <span>{inv.customer}</span>
+      <span className="text-xs">{inv.dueDate}</span>
+      <span>{inv.amount}</span>
+    </div>
+  ));
+}
+```
+
+```tsx
+// AFTER — name leads, value anchors right, metadata recedes
+<div className="divide-border divide-y">
+  {invoices.map((inv) => (
+    <div key={inv.id} className="flex items-center gap-3 px-4 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">
+          Due {formatDate(inv.dueDate)}
+        </p>
+      </div>
+      <span className="shrink-0 text-right text-base font-semibold tabular-nums">
+        {formatCurrency(inv.amount)}
+      </span>
+    </div>
+  ))}
+</div>
+```
+
+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.
+
+## 2. Bare stat grid → hero KPI with supporting stats
+
+**Failure:** four equal chips. The widget's one question ("how are we
+doing?") has no answer — every number claims the same importance.
+
+```tsx
+// BEFORE — nothing is the headline
+<div className="grid grid-cols-2 gap-2 p-4">
+  <div className="text-sm">Revenue: {revenue}</div>
+  <div className="text-sm">Orders: {orders}</div>
+  <div className="text-sm">Avg: {avg}</div>
+  <div className="text-sm">Refunds: {refunds}</div>
+</div>
+```
+
+```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>
+</div>
+
+<div className="flex shrink-0 items-center border-t">
+  {[
+    { label: 'Orders', value: orders },
+    { label: 'Avg order', value: formatCurrency(avg) },
+    { label: 'Refunds', value: refunds },
+  ].map((stat, i) => (
+    <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>
+      </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.
+
+## 3. Unstyled status → semantic badge or dot
+
+**Failure:** status as bare text, or hardcoded palette (`bg-green-500`) that
+breaks in dark mode and off-brand tenants.
+
+```tsx
+// BEFORE
+<span className="text-xs">{sub.status}</span>
+// or
+<span className="rounded bg-green-500 px-1 text-white">{sub.status}</span>
+```
+
+```tsx
+// AFTER — Badge variants carry the semantics; the map is the single source
+import { Badge } from '@ekanos/ui/badge';
+
+const STATUS_VARIANT = {
+  active: 'success',
+  trialing: 'info',
+  past_due: 'warning',
+  canceled: 'destructive',
+} as const;
+
+<Badge variant={STATUS_VARIANT[sub.status] ?? 'outline'}>
+  {STATUS_LABEL[sub.status] ?? sub.status}
+</Badge>;
+```
+
+When a badge is too loud (dense lists), use a dot plus muted text instead:
+
+```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>
+```
+
+One status treatment per row. A row with a colored badge AND a colored icon
+AND colored money is signalling nothing.
+
+## 4. Cramped card → sizing floors applied
+
+**Failure:** `p-2`, `space-y-1`, `text-xs` everywhere, `h-3 w-3` icons. Dense
+is not information-rich; it is unreadable.
+
+```tsx
+// BEFORE
+<div className="space-y-1 p-2">
+  {events.map((e) => (
+    <div key={e.id} className="flex gap-1 text-xs">
+      <Icon name="fa-light fa-bolt" className="h-3 w-3" />
+      <span>{e.title}</span>
+    </div>
+  ))}
+</div>
+```
+
+```tsx
+// AFTER — floors: rows px-4 py-3, icons h-5 w-5, body text-sm+
+<div className="divide-border divide-y">
+  {events.slice(0, 6).map((e) => (
+    <div key={e.id} className="flex items-start gap-3 px-4 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>
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-base font-medium">{e.title}</p>
+        <p className="text-muted-foreground text-sm">{e.summary}</p>
+      </div>
+      <span className="text-muted-foreground shrink-0 text-xs">
+        {formatTimeAgo(e.at)}
+      </span>
+    </div>
+  ))}
+</div>
+```
+
+If the content no longer fits after applying floors, show fewer items — the
+floors are not negotiable, the item count is.
+
+## 5. Overflowing card → inner scroll + "View all"
+
+**Failure:** the list grows the card past its grid slot, or a fixed
+`max-h-[180px]` caps it arbitrarily and clips the last row.
+
+```tsx
+// BEFORE — the card scrolls (or grows); a magic pixel height fights the grid
+<div className="max-h-[180px] overflow-y-auto">{rows}</div>
+```
+
+```tsx
+// AFTER — the LIST scrolls inside the flex column; the card holds its size
+import { Button } from '@ekanos/ui/button';
+
+<div className="flex h-full min-h-0 flex-col">
+  <div className="min-h-0 flex-1 overflow-y-auto">
+    <div className="divide-border divide-y">{rows}</div>
+  </div>
+  {items.length > 7 && (
+    <div className="shrink-0 border-t px-4 py-2">
+      <Button variant="ghost" size="sm" className="text-muted-foreground">
+        View all {items.length}
+      </Button>
+    </div>
+  )}
+</div>;
+```
+
+`min-h-0` is the load-bearing class — without it the flex child refuses to
+shrink and nothing scrolls. Test at the sm viewport preset, where the failure
+actually shows.
+
+## 6. Button pile-up → one action + menu
+
+**Failure:** two or three buttons per row; the row becomes a toolbar.
+
+```tsx
+// AFTER — one visible action, the rest behind a menu
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@ekanos/ui/dropdown-menu';
+
+<div className="flex shrink-0 items-center gap-2">
+  <Button size="sm">Pay now</Button>
+  <DropdownMenu>
+    <DropdownMenuTrigger
+      render={<Button variant="ghost" size="icon" className="h-8 w-8" />}
+    >
+      <Icon name="fa-light fa-ellipsis-vertical" className="h-4 w-4" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuItem>View details</DropdownMenuItem>
+      <DropdownMenuItem>Payment history</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</div>;
+```
+
+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
+
+**Failure:** an empty array renders an empty card, indistinguishable from a
+bug. Empty is a state you design, distinct from error.
+
+```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>
+```
+
+No CTA unless there is a real action the user can take from the dashboard.