前端设计

Enforce the skillshare design system across the two frontends. $ARGUMENTS is the file or area being worked on.

Companion skill: For UX design decisions beyond token/component usage — layout strategy, information hierarchy, interaction patterns, micro-copy, or when designing a new page from scratch — also invoke /ui-ux-pro-max for higher-level design guidance. This skill handles what components and tokens to use; /ui-ux-pro-max handles how to design the experience.

The project has two distinct design systems sharing semantic color names but with different visual treatments:

UI Dashboard (ui/)

Reference implementation: ui/src/pages/LogPage.tsx

For the full human-readable style guide (design philosophy, visual rules, anti-patterns), see references/STYLE_GUIDE.md bundled with this skill.

Design Tokens

Defined in ui/src/index.css (@theme) and ui/src/design.ts:

// ui/src/design.ts
import { radius, shadows, palette } from '../design';

radius.sm   // '4px'  — badges, chips
radius.md   // '8px'  — cards, containers
radius.lg   // '12px' — modals, panels
radius.btn  // '9999px' — pill buttons (skillshare style)
radius.full // '9999px' — avatars

shadows.sm / .md / .lg / .hover / .active / .accent / .blue
palette.accent / .info / .success / .warning / .danger

Color Tokens (Tailwind classes)

Rule: Max one accent color per visual region. Don't double up — if a row has a colored dot, skip the colored badge (or vice versa).

Typography

• Body: DM Sans (via --font-hand)
• font-mono: timestamps, file paths, durations, code, hashes
• uppercase tracking-wider: command names, stat labels
• Size: text-2xl > text-xl > text-base > text-sm > text-xs

Page Structure (mandatory order)

Every page follows this layout:

<div className="space-y-5 animate-fade-in">
  <PageHeader icon={<Icon />} title="..." subtitle="..." actions={<>...</>} />

  {/* Toolbar: tabs + filters */}
  <div className="flex flex-wrap items-end gap-3">
    <SegmentedControl ... />
    <Select ... />
  </div>

  {/* Summary line or stat cards */}
  <SummaryLine ... />

  {/* Content: table, card list, or card grid */}
  {empty ? <EmptyState ... /> : <ContentArea />}

  {/* Dialogs (rendered at bottom, portal via DialogShell) */}
  <ConfirmDialog ... />
</div>

Component Library

Stats Patterns (choose one)

Status Patterns (choose one per element)

List Patterns

Button Variants

Separator

Always: border-dashed border-pencil-light/30 (unified opacity, not /20 or /40)

Animations

Keyboard Shortcuts

Registered in KeyboardShortcutsModal.tsx and useGlobalShortcuts.ts:

• ? — shortcuts modal
• / — focus search
• g d/s/t/l — go to Dashboard/Skills/Targets/Log
• r — refresh page
• Only fire when no <input> / <textarea> focused
• Chord timeout: 500ms
• New shortcuts must be added to KeyboardShortcutsModal
• Never override browser-native shortcuts (Cmd+C, etc.)

Accessibility

Card Overflow Gotcha

Card.tsx has overflow-hidden by default for border-radius clipping. Absolute-positioned children (dropdowns, tooltips) get clipped. Fix: pass overflow prop or add className="!overflow-visible".

Data Fetching Pattern

Pages use @tanstack/react-query:

const { data, isPending } = useQuery({
  queryKey: queryKeys.someKey(...),
  queryFn: () => api.someEndpoint(...),
  staleTime: staleTimes.someCategory,
});

• Query keys: ui/src/lib/queryKeys.ts
• API client: ui/src/api/client.ts
• App context: ui/src/context/AppContext.tsx provides { isProjectMode, projectRoot }

Website (website/)

Docusaurus with hand-drawn "sketchy organic" design in website/src/css/custom.css.

Key Differences from UI Dashboard

• Wobbly borders: border-radius: var(--radius-wobbly) (not clean px values)
• Hard shadows: 4px 4px 0px 0px #2d2d2d (no blur)
• Dot grid bg: radial-gradient(var(--color-muted) 1px, transparent 1px) on body
• Post-it yellow: --color-postit: #fff9c4 for highlights
• Dashed borders everywhere: navbar, sidebar, tables, pagination, code blocks
• Button hover: transform: translate(2px, 2px) + shadow shrinks (press-down feel)
• Links: wavy underline (text-decoration-style: wavy)
• Dark mode: amber/gold primary (#e8a84c) instead of blue

CSS Variables

See website/src/css/custom.css for full list. Key additions beyond shared palette:

• --radius-wobbly[-sm|-md|-btn] — hand-drawn border-radius
• --color-postit[-dark] — yellow highlight
• --shadow-md: 4px 4px 0px 0px #2d2d2d — hard offset
• --card-bg, --card-border, --install-bg — component-specific

Docusaurus Classes

• .button--primary — green bg, pencil border, hard shadow
• .button--secondary — dashed border, no fill
• .markdown h2 — dashed bottom border
• .admonition — wobbly border-radius, left stripe
• .menu__link--active — post-it yellow background
• .target-badge — wobbly border for target grid
• Code blocks get box-shadow: 4px 4px 0px 0px #101827

Homepage Components (website/src/pages/index.tsx)

• CARD_ROTATIONS array for random hand-drawn tilt
• WavyDivider — SVG dashed wavy line between sections
• InstallTabs — tabbed install commands with copy button
• Hero has hand-drawn SVG connector + underline

Anti-Patterns (Both Systems)

Checklist Before Submitting

• Uses existing components (Card, Badge, Button, etc.) — no custom markup for solved patterns
• Page follows PageHeader → Toolbar → Summary → Content structure
• Color tokens from Tailwind (text-pencil, not hardcoded #141312)
• Separator is border-dashed border-pencil-light/30
• Empty states use <EmptyState>
• Destructive actions use <ConfirmDialog>
• All icon buttons have aria-label
• New shortcuts registered in KeyboardShortcutsModal
• animate-fade-in on root container
• Dark mode works (check both themes)