Design System Skill

Read .hackathon/IDEA-FINAL.md for product context and .hackathon/STACK.md for technical constraints.

Hard gate: Scaffold must be complete (the UI package must exist at packages/ui/).

Philosophy

The design system has one job: make everything look intentionally designed and consistent without anyone spending time on per-page styling decisions. In a hackathon, the difference between "student project" and "production app" is usually:

• Consistent spacing and typography
• A coherent color palette
• 5-8 well-designed reusable components
• Micro-interactions that signal quality (hover states, transitions, loading states)

We are NOT building a comprehensive design system. We're building the minimum set of tokens and components that make everything look like it belongs together.

Anti-Patterns to Avoid

Read references/anti-patterns.md for a detailed list. The short version:

• No purple-gradient-on-white (the universal AI app look)
• No Inter/Roboto/system fonts as the only typography
• No generic shadcn defaults without customization
• No pure white backgrounds (add warmth or coolness)
• No identical-looking cards everywhere

Process

Step 1: Aesthetic Direction

Based on the product idea, decide on an aesthetic direction. Ask the team:

• What feeling should the product evoke? (Professional trust? Playful speed? Technical precision?)
• What similar products do you admire the look of?
• Light mode, dark mode, or adaptive?

Capture this in .hackathon/design/DESIGN-BRIEF.md.

Step 2: Design Tokens

Define in packages/ui/src/tokens/:

Colors — A cohesive palette:

• Primary (brand color + shades)
• Secondary (accent color)
• Neutral (grays for text, borders, backgrounds)
• Semantic (success, warning, error, info)
• Surface (background colors — NOT pure white)

Typography:

• Display font (for headings — something distinctive via Google Fonts)
• Body font (for readable text — can be more standard but not generic)
• Mono font (for any code/data display)
• Size scale (sm, base, lg, xl, 2xl, 3xl)

Spacing: Use Tailwind's default scale but define semantic aliases:

• space-tight: 0.5rem
• space-base: 1rem
• space-loose: 1.5rem
• space-section: 3rem

Radii, Shadows, Transitions: Pick one consistent set and stick to it.

Step 3: Core Components

Build these in packages/ui/src/components/. Each component should:

• Accept reasonable props (variant, size, disabled, etc.)
• Use the design tokens for all visual properties
• Include hover/focus/active states
• Include a loading state where applicable
• Be exported from packages/ui/src/index.ts

Required components (minimum set):

1. Button — primary, secondary, ghost, danger variants; sizes sm/md/lg
2. Card — with optional header, body, footer sections
3. Input — text input with label, helper text, error state
4. Badge — for status indicators
5. Layout — page wrapper with consistent padding and max-width
6. LoadingSpinner — consistent loading indicator
7. EmptyState — for when there's no data yet
8. FileUpload — drag-and-drop zone (if relevant to the project)

Optional but impactful:

• Toast / notification system
• Modal / dialog
• ProgressBar
• DataTable (if showing tabular data)

Step 4: Tailwind Configuration

Update the frontend's tailwind.config.ts to use the design tokens:

• Custom colors mapped to the palette
• Custom fonts added
• Any custom utilities needed

Step 5: Demo Page

Create a simple page (could be at /design-system in the frontend app, removed before demo) that shows all components in various states. This serves as:

• Visual verification that everything looks good together
• A reference for developers using the components
• A conversation piece if the team wants to adjust the aesthetic

Output

• packages/ui/ fully populated with components and tokens
• Updated tailwind.config.ts in the frontend app
• .hackathon/design/DESIGN-BRIEF.md — aesthetic direction
• .hackathon/design/colors.md — color palette reference
• .hackathon/design/components.md — component inventory and usage
• Demo page in the frontend app
• Update STATE.md, log to changelog