frontend-spec

name: frontend-spec description: Generate a frontend component specification for React + TypeScript components in Label Suite.

Frontend Component Specification

Generate a detailed frontend specification for React + TypeScript components including wireframe, props interface, state management, API integration, and testing.

Usage

/frontend-spec "AnnotationWorkspace — main annotation interface for annotators"
/frontend-spec "Leaderboard — ranked submission results table"
/frontend-spec "TaskConfigForm — admin form for creating annotation tasks"

Output Format

# Frontend Specification: [ComponentName]

**Component**: `frontend/src/components/[ComponentName].tsx`
**Page**: `frontend/src/pages/[PageName].tsx`
**Date**: YYYY-MM-DD
**Spec Reference**: specs/NNN-feature/spec.md

---

## Wireframe (ASCII)

┌─────────────────────────────────────────────────┐ │ Label Suite [User] [Logout]│ ├─────────────────────────────────────────────────┤ │ Task: Text Classification — Sentiment Analysis │ │ Deadline: 2026-03-31 | Submissions: 2/10 │ ├─────────────────────────────────────────────────┤ │ │ │ Item 1 of 500 │ │ ┌────────────────────────────────────────────┐ │ │ │ "The product quality exceeded expectations"│ │ │ └────────────────────────────────────────────┘ │ │ │ │ Label: ○ Positive ○ Negative ○ Neutral │ │ │ │ [← Previous] [Next →] │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ [Submit All Predictions] │ │ │ └────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘

---

## TypeScript Interfaces

```typescript
// Task configuration from API (config-driven)
interface TaskConfig {
  task_id: number;
  name: string;
  task_type: 'text-classification' | 'sequence-labeling' | 'text-generation';
  labels?: string[];       // for classification tasks
  deadline: string;        // ISO 8601
  max_submissions: number;
  submissions_used: number;
}

// Individual annotation item
interface AnnotationItem {
  item_id: number;
  input_text: string;
  position: number;
  total: number;
}

// Component props
interface AnnotationWorkspaceProps {
  taskId: number;
  onSubmitSuccess: (submissionId: number) => void;
}

// Component state
interface AnnotationWorkspaceState {
  task: TaskConfig | null;
  currentItem: AnnotationItem | null;
  predictions: Record<number, string>;  // item_id → label
  currentIndex: number;
  status: 'loading' | 'annotating' | 'submitting' | 'submitted' | 'error';
  errorMessage: string | null;
}

State Management

Local State

State Diagram

stateDiagram-v2
    [*] --> loading: Component mounts
    loading --> annotating: Task + items loaded
    loading --> error: API error
    annotating --> submitting: Submit clicked
    submitting --> submitted: 201 Created
    submitting --> error: API error or rate limit
    error --> annotating: User dismisses error
    submitted --> [*]

Event Handlers

Keyboard Events:

API Integration

Validation Rules

Loading & Error States

// Loading skeleton
<div role="status" aria-label="Loading annotation task">
  <Skeleton height={80} />
  <Skeleton count={3} />
</div>

// Error state
<Alert variant="error" role="alert">
  <p>{errorMessage}</p>
  <button onClick={handleErrorDismiss}>Dismiss</button>
</Alert>

// Submission confirmation
<Alert variant="success" role="status" aria-live="polite">
  Predictions submitted! Submission ID: {submissionId}
</Alert>

Security

• No dangerouslySetInnerHTML — annotation text rendered as {item.input_text} (escaped)
• JWT token stored in memory or httpOnly cookie — NOT localStorage
• No sensitive data (scores before completion) rendered from local state

Accessibility (WCAG 2.1 AA)

Responsive Design

Testing

Key Playwright Test Cases:

test('annotator completes annotation and submits', async ({ page }) => {
  await page.goto('/tasks/42/annotate');
  await page.getByRole('radio', { name: 'Positive' }).click();
  await page.getByRole('button', { name: 'Next' }).click();
  // ... annotate all items
  await page.getByRole('button', { name: 'Submit All Predictions' }).click();
  await expect(page.getByRole('status')).toContainText('Predictions submitted');
});

Dependencies