ux-ui - SKILL.md Agent Skill

name: ux-ui description: "UI/UX redesign and improvement skill for HeadsUp pages and components. Responsible for implementing the 'Soft Modern' design system across all pages. Use when: (1) Redesigning or improving any page's UI/layout, (2) Creating or refactoring reusable Phoenix function components, (3) Auditing current UI against the design system, (4) Updating design documentation in project_doc/docs/design/, (5) Building mobile-first responsive layouts, (6) Implementing the 3-column social feed layout pattern. Triggers on requests involving visual redesign, component extraction, UI improvements, mobile responsiveness, or design system compliance." argument-hint: "<page-name|component|audit|all>"

HeadsUp UX/UI Redesign Skill

Redesign and improve HeadsUp pages using the "Soft Modern" aesthetic with mobile-first, component-driven architecture.

Source of Truth

Primary: project_doc/docs/design/ux-ui.md - Design system DNA
Secondary: project_doc/docs/design/style-guide.md - Brand foundations
Page specs: project_doc/docs/design/pages/*.md - Per-page wireframes

If guidance conflicts between files, ux-ui.md takes priority.

Design References

The UI follows a social media feed pattern inspired by these reference designs:

3-column layout: left sidebar (categories/nav), center feed, right sidebar (suggestions/popular)
Warm blush background (#FFF5F2) with white cards
Rounded corners (24px cards, 12px buttons), soft shadows
Avatar-driven post cards with engagement metrics
Pastel-colored tags/badges
Mobile: collapses to single-column with bottom nav

Arguments

$ARGUMENTS = target to redesign

Argument	Action
`home`	Redesign home/landing page
`goals`	Redesign goals listing page
`goal-detail`	Redesign single goal view
`challenges`	Redesign challenges pages
`profile`	Redesign user profile page
`create`	Redesign create goal/challenge forms
`groups`	Redesign groups page
`people`	Redesign people/connections page
`admin`	Redesign admin pages
`component:<name>`	Create/improve a specific reusable component
`audit`	Audit all pages against design system
`all`	Full redesign of all pages

Workflow

Step 1: Read Design Context

Read project_doc/docs/design/ux-ui.md (design DNA)
Read the relevant page spec from project_doc/docs/design/pages/
Read current implementation files (LiveView + templates)
Read lib/heads_up_web/components/ for existing shared components

Step 2: Identify Reusable Components

Before writing any page-level code, extract shared UI elements into function components.

Component location: lib/heads_up_web/components/

Component checklist - see references/component-library.md for full patterns:

avatar.ex - User avatars (sizes: sm/md/lg/xl)
card.ex - Base card wrapper with soft shadow
post_card.ex - Feed post card (avatar, content, media, engagement)
tag.ex - Pastel tag/badge component
stat_badge.ex - Numeric stat with label
sidebar_card.ex - Right sidebar suggestion/popular card
category_card.ex - Left sidebar category card
empty_state.ex - Empty state with icon + message + CTA
skeleton.ex - Loading skeleton components
engagement_bar.ex - Like/comment/share action bar
progress_bar.ex - Goal/challenge progress indicator
section_header.ex - Section title with "View All" link
user_mini_card.ex - Small user card for suggestions/mentions
bottom_nav.ex - Mobile bottom navigation bar

Step 3: Implement Mobile-First

Build all layouts mobile-first using Tailwind breakpoints:

/* Base = mobile (0-639px) */
<div class="flex flex-col gap-4">

/* Tablet (sm: 640px+) */
<div class="sm:grid sm:grid-cols-2 sm:gap-6">

/* Desktop (lg: 1024px+) */
<div class="lg:grid lg:grid-cols-12 lg:gap-8">
  <aside class="hidden lg:block lg:col-span-3">  <!-- Left sidebar -->
  <main class="lg:col-span-6">                    <!-- Center feed -->
  <aside class="hidden lg:block lg:col-span-3">  <!-- Right sidebar -->
</div>

Mobile patterns:

Single column stack
Bottom navigation bar (fixed)
Horizontal scroll for categories
Cards full-width with 16px padding
Tap-friendly targets (min 44px)

Step 4: Apply Design Tokens

Apply these exact values from the design system:

Token	Value	Tailwind
Background	`#FFF5F2`	`bg-[#FFF5F2]`
Card bg	`#FFFFFF`	`bg-white`
Card radius	`24px`	`rounded-3xl`
Card shadow	`0 4px 20px rgba(0,0,0,0.05)`	`shadow-[0_4px_20px_rgba(0,0,0,0.05)]`
Card padding	`24px`	`p-6`
Button radius	`12px` or pill	`rounded-xl` or `rounded-full`
Input bg	`#F9FAFB`	`bg-gray-50`
Input radius	`12px`	`rounded-xl`
Input height	`48px`	`h-12`
Primary text	`#111827`	`text-gray-900`
Secondary text	`#6B7280`	`text-gray-500`
Tertiary text	`#9CA3AF`	`text-gray-400`
Primary brand	`#FF6B6B`	`text-[#FF6B6B]`
Interactive blue	`#3B82F6`	`text-blue-500`
Gap between cards	`24px`	`gap-6`
Gap between elements	`16px`	`gap-4`

Step 5: Build the Page

Create/update the LiveView render function
Use extracted components via function calls
Implement all states: loaded, loading (skeletons), empty, error
Test responsive behavior at all breakpoints

Step 6: Update Design Docs

After implementation, update the relevant page doc in project_doc/docs/design/pages/:

Mark implemented sections
Note any deviations from the spec
Add component references used

Component Architecture Rules

One component per file in lib/heads_up_web/components/
Use attr and slot declarations for all function components
Default variants via attr :variant, :atom, default: :default
Size props via attr :size, :atom, values: [:sm, :md, :lg], default: :md
Composable - components accept slots for customization
No business logic - components are purely presentational

References

references/component-library.md - Full component patterns with code examples
references/design-tokens.md - Complete design token reference and Tailwind mappings