mcouthon/agents/power-ui

Power-UI Construction Manual

Patterns and checklists for power-user interfaces: information-dense, fully keyboard-operable, AI-present. Stack: React + TypeScript + Tailwind CSS. Adapt token names to your design system.

0. When to Use This Skill

Target Archetype

This skill is for power-user tools — apps where the primary user is a daily-driver who values speed, density, and keyboard mastery over discoverability and onboarding.

Good fits: personal dashboards, admin consoles, developer tools, triage interfaces, AI command centers, ops tools.

Not for: marketing sites, onboarding flows, consumer apps prioritizing discoverability, or tools where most users are occasional visitors. For those, use /design alone.

Relationship with /design

The /design skill builds your visual foundation — tokens, typography, color, shadows, animation system, component styling. This skill layers interaction architecture on top: keyboard navigation, information density, AI presence, page structure.

Workflow: Start with /design for tokens and primitives → apply this skill for page structure and interaction patterns.

When both skills apply, this skill overrides these /design defaults:

Everything not in this table follows /design as-is. The two skills are complementary, not competing.

1. Principles

1. Dense over spacious. Every pixel earns its place. List rows are 36–40px. Cards are for detail panels — not data grids.
2. Keyboard-first. Any task achievable by mouse must be achievable by keyboard. j/k to move, Enter to act, Escape to retreat.
3. AI is a first-class citizen. Contextual "Ask AI" buttons are surface-level — not buried in menus or settings.
4. Signal over decoration. Color, weight, and icons carry semantic meaning. No chrome for its own sake.
5. Progressive reveal. Actions appear on hover/focus — they don't consume permanent space.
6. The interface feels alive. Background activity is visible — pulse indicators, shimmer loading, real-time updates. Static screens feel broken.

1.1 Color Discipline

Color is signal, not decoration. Every hue must answer: "what does this tell the user?" If the answer is nothing, use monochrome.

Hue budget example (adapt hues/tokens to your palette):

An info hue (blue) may exist but should be rare — informational banners only, never alongside more than 2 other semantic hues on one screen.

2. Component Patterns

Token convention: Code examples below use raw Tailwind values

(text-[11px], bg-white/[0.03]) for portability. In your project,

replace these with semantic tokens from your design system:

| Example value | Replace with | Purpose |

| -------------------------- | ------------------- | ------------------- |

| text-[11px] | text-caption | Caption/label text |

| text-[13px] | text-body-sm | Body text (small) |

| bg-white/[0.03] | bg-surface-hover | Subtle hover state |

| text-primary/70 | text-accent-muted | Muted accent text |

| text-muted-foreground/50 | text-faint | Faintest text level |

See the /design skill for building your token system.

Theme note: Examples use dark-mode-first values. For light mode,

invert the opacity pattern: bg-black/[0.03] instead of bg-white/[0.03].

2.1 Section Label

Replace generic page <h1> headers with a structured label: ALL-CAPS entity name · count + optional meta + far-right action cluster.

interface SectionLabelProps {
  label: string; // ALL-CAPS, e.g. "ISSUES"
  count?: number;
  meta?: string; // e.g. "12 unread"
  actions?: React.ReactNode;
}
function SectionLabel({ label, count, meta, actions }: SectionLabelProps) {
  return (
    <div className="flex items-center gap-3 py-2">
      <span className="text-[11px] font-medium uppercase tracking-widest text-muted-foreground">
        {label}
      </span>
      {count !== undefined && (
        <span className="font-mono text-[11px] tabular-nums text-muted-foreground/50">
          · {count}
        </span>
      )}
      {meta && (
        <span className="ml-auto text-[11px] text-muted-foreground/50">
          {meta}
        </span>
      )}
      {actions && (
        <div className={cn("flex items-center gap-1.5", !meta && "ml-auto")}>
          {actions}
        </div>
      )}
    </div>
  );
}

2.2 Data-Table Row (36–40px)

All list views use flat, fixed-height rows. Never use cards for data grids.

Anatomy:

[Visual] [Identifier] [Title ·············] [Meta] [Timestamp] [Hover actions]

• Visual — status dot, priority bars, or source icon (14px, shrink-0)
• Identifier — short ID, font-mono text-[11px] tabular-nums text-primary/70 shrink-0
• Title — min-w-0 flex-1 truncate text-[13px], bold for unread, muted for seen
• Timestamp — w-8 font-mono text-[11px] tabular-nums text-muted-foreground/50 shrink-0
• Hover actions — opacity-0 group-hover:opacity-100, 28px icon buttons

function DataRow({
  id,
  title,
  isNew,
  isFocused,
  isActive,
  timestamp,
  onSelect,
  onAction,
  rowRef,
}) {
  return (
    <div
      ref={rowRef}
      role="row"
      tabIndex={-1}
      aria-selected={isActive}
      onClick={onSelect}
      className={cn(
        "group flex items-center h-9 px-3 gap-2 cursor-pointer border-b border-border transition-colors duration-75",
        "hover:bg-white/[0.03]",
        isActive && "bg-primary/[0.08] border-l-2 border-l-primary",
        isFocused && !isActive && "bg-white/[0.05]",
        isFocused && "ring-1 ring-inset ring-primary/30",
      )}
    >
      <span
        className={cn(
          "inline-block h-2 w-2 rounded-full",
          isNew ? "bg-blue-400" : "bg-muted-foreground/40",
        )}
      />
      <span className="shrink-0 font-mono text-[11px] tabular-nums text-primary/70">
        {id}
      </span>
      <span
        className={cn(
          "min-w-0 flex-1 truncate text-[13px]",
          isNew ? "font-medium" : "text-muted-foreground",
        )}
      >
        {title}
      </span>
      <div className="ml-auto flex items-center gap-2 shrink-0">
        <span className="w-8 text-right font-mono text-[11px] tabular-nums text-muted-foreground/50">
          {timestamp}
        </span>
      </div>
      {/* Hover action cluster — see Section 2.2 hover pattern */}
      <div
        className="flex items-center gap-0.5 shrink-0 opacity-0 group-hover:opacity-100 transition-opacity"
        onClick={(e) => e.stopPropagation()}
      >
        <Tooltip content="Archive (e)">
          <button
            type="button"
            className="p-1 rounded-sm text-muted-foreground hover:text-foreground hover:bg-surface-raised"
            onClick={() => onAction("archive")}
            aria-label="Archive"
          >
            <Archive size={13} />
          </button>
        </Tooltip>
        <Tooltip content="Ask AI (a)">
          <button
            type="button"
            className="p-1 rounded-sm text-muted-foreground hover:text-foreground hover:bg-surface-raised"
            onClick={() =>
              askAI(navigate, `Tell me about: "${title}" (ID: ${id})`)
            }
            aria-label="Ask AI"
          >
            <MessageSquare size={13} />
          </button>
        </Tooltip>
      </div>
    </div>
  );
}

2.3 Slide-Over Drawer (Detail Panel)

Detail views open as a right-side slide-over (~55vw) — not inline expansion, not a modal. Row click or Enter opens it; Escape or backdrop click closes it.

function SlideOver({
  open,
  onClose,
  children,
}: {
  open: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  return (
    <>
      {open && (
        <div
          className="fixed inset-0 z-40 bg-black/20"
          onClick={onClose}
          aria-hidden
        />
      )}
      <div
        className={cn(
          "fixed right-0 top-0 bottom-0 z-50 w-[55vw] max-w-3xl bg-surface border-l border-border",
          "transition-transform duration-200 ease-out",
          open ? "translate-x-0" : "translate-x-full",
        )}
        role="dialog"
        aria-modal="true"
      >
        <div className="flex flex-col h-full overflow-hidden">{children}</div>
      </div>
    </>
  );
}