Skip to content

UI-SPEC.md

Latest commit

 

History

History
151 lines (123 loc) · 5.7 KB

UI-SPEC.md

File metadata and controls

151 lines (123 loc) · 5.7 KB
Raw

UI Specification

Project Design System

  • Generated by: /ui-spec command
  • Preferred styling system: Tailwind CSS

Design Tokens

Color Palette

Selected: portfolio - Portfolio / Personal

Role Hex Usage
Primary #18181B Main actions, active states, primary buttons
Secondary #3F3F46 Supporting elements, secondary buttons
Accent #2563EB Links, highlights, focus rings, badges
Background #FAFAFA Page background
Surface #FFFFFF Cards, form panels, elevated sections
Text #18181B Body text, headings
Text Muted #71717A Captions, placeholders, secondary labels
Border #E4E4E7 Dividers, input borders, card outlines
Success #22C55E Confirmations, task saved feedback
Warning #EAB308 Caution messages, approaching deadlines
Danger #EF4444 Delete actions, error states

Typography

Font Pairing

Selected: tech-startup - Tech / Startup

  • Heading: Space Grotesk
  • Body: DM Sans

Google Fonts import:

<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&family=Space+Grotesk:wght@500;600;700&display=swap" rel="stylesheet">

Accessibility Requirements

  • Text on background: minimum 4.5:1 contrast ratio (WCAG AA)
  • Interactive elements: visible focus indicators (2px solid ring using Accent #2563EB)
  • Touch targets: minimum 44x44px - use padding on buttons and links
  • Images: descriptive alt text on all meaningful images
  • Icon-only buttons: aria-label attribute required (delete button, etc.)

UX Rules Checklist

  • color-contrast (CRITICAL) - All text/background combos must pass 4.5:1 minimum. Verify muted text on surface and background.
  • focus-states (CRITICAL) - Every button, input, and link must show a visible focus ring. Never use outline: none without a replacement.
  • touch-targets (CRITICAL) - All buttons and interactive elements must be at least 44x44px. Use padding on small controls.
  • aria-labels (CRITICAL) - Delete button and any icon-only actions must have aria-label.
  • alt-text (CRITICAL) - Any images or decorative elements need appropriate alt text or alt="".
  • font-size-minimum (HIGH) - Base body font is 16px minimum. Use rem units throughout.
  • line-height (HIGH) - Body text uses line-height: 1.6. Headings use 1.2-1.3.
  • no-horizontal-scroll (HIGH) - No element exceeds viewport width. Test at 320px minimum.
  • loading-states (HIGH) - Show loading feedback during task fetch, create, and delete operations (spinner or skeleton).
  • error-placement (HIGH) - Inline errors appear below the relevant input field, not only at page top.
  • form-labels (HIGH) - All inputs have a visible <label> element. Placeholder text is never the only label.
  • color-not-only-indicator (HIGH) - Success/error states combine color with an icon or text label.
  • disable-during-async (MEDIUM) - Submit and delete buttons are disabled while a request is in flight.
  • cursor-pointer (MEDIUM) - All clickable elements show cursor: pointer on hover.
  • consistent-spacing (MEDIUM) - Use Tailwind's default 4px scale only. No arbitrary values.
  • responsive-breakpoints (MEDIUM) - Test at 320px, 640px, 768px, 1024px, 1280px.
  • animation-duration (MEDIUM) - Transitions use 150ms for hover, 200ms for modals/overlays.
  • no-emoji-icons (MEDIUM) - Use Lucide or Heroicons SVG icons. No emoji as functional UI elements.
  • consistent-icon-sizing (MEDIUM) - Inline icons: 16px. Button icons: 20px. No mixing within the same context.

Technical Setup

Tailwind Config

// tailwind.config.js > theme > extend
{
  colors: {
    primary: '#18181B',
    secondary: '#3F3F46',
    accent: '#2563EB',
    background: '#FAFAFA',
    surface: '#FFFFFF',
    text: '#18181B',
    'text-muted': '#71717A',
    border: '#E4E4E7',
    success: '#22C55E',
    warning: '#EAB308',
    danger: '#EF4444',
  },
  fontFamily: {
    heading: ['Space Grotesk', '-apple-system', 'BlinkMacSystemFont', 'sans-serif'],
    body: ['DM Sans', '-apple-system', 'BlinkMacSystemFont', 'sans-serif'],
  },
}

CSS Variables

:root {
  /* Colors */
  --color-primary: #18181B;
  --color-secondary: #3F3F46;
  --color-accent: #2563EB;
  --color-background: #FAFAFA;
  --color-surface: #FFFFFF;
  --color-text: #18181B;
  --color-text-muted: #71717A;
  --color-border: #E4E4E7;
  --color-success: #22C55E;
  --color-warning: #EAB308;
  --color-danger: #EF4444;

  /* Typography */
  --font-heading: 'Space Grotesk', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-body: 'DM Sans', -apple-system, BlinkMacSystemFont, sans-serif;
}

Note: Use these classes/variables instead of hardcoding hex values. Update one token and it changes everywhere.

Component Notes

Task List

  • Clean table or card list on a surface (#FFFFFF) panel sitting on background (#FAFAFA)
  • Deadline dates use text-muted when far away, warning color when within 3 days, danger when past due
  • Row hover: subtle border color background shift (#E4E4E7 at 40% opacity or Tailwind hover:bg-zinc-100)

Add Task Form

  • Sits below or beside the task list on the same page
  • Input borders use border color, focus ring uses accent blue
  • Submit button: primary background, white text, rounded corners

Delete Button

  • Uses danger color (#EF4444)
  • Icon-only or icon+text - must have aria-label="Delete task"
  • Shows a spinner and disables during the delete request

Feedback Messages

  • Success: success green with a checkmark icon
  • Error: danger red with an X icon
  • Brief inline display - no full-page redirects (replaces TempData flash messages from v1)