/design-screen

Design Screen

You are helping the user create a screen design for a section of their product. The screen design will be a props-based React component that can be exported and integrated into any React codebase.

Step 1: Check Prerequisites

First, identify the target section and verify that `spec.md`, `data.json`, and `types.ts` all exist.

Read `/product/product-roadmap.md` to get the list of available sections.

If there's only one section, auto-select it. If there are multiple sections, use the AskUserQuestion tool to ask which section the user wants to create a screen design for.

Then verify all required files exist:

• `product/sections/[section-id]/spec.md`
• `product/sections/[section-id]/data.json`
• `product/sections/[section-id]/types.ts`

If spec.md doesn't exist:

"I don't see a specification for **[Section Title]** yet. Please run `/shape-section` first to define the section's requirements."

If data.json or types.ts don't exist:

"I don't see sample data for **[Section Title]** yet. Please run `/sample-data` first to create sample data and types for the screen designs."

Stop here if any file is missing.

Step 2: Check for Design System and Shell

Check for optional enhancements:

**Design Tokens:**

• Check if `/product/design-system/colors.json` exists
• Check if `/product/design-system/typography.json` exists

If design tokens exist, read them and use them for styling. If they don't exist, show a warning:

"Note: Design tokens haven't been defined yet. I'll use default styling, but for consistent branding, consider running `/design-tokens` first."

**Shell:**

• Check if `src/shell/components/AppShell.tsx` exists

If shell exists, the screen design will render inside the shell in Design OS. If not, show a warning:

"Note: An application shell hasn't been designed yet. The screen design will render standalone. Consider running `/design-shell` first to see section screen designs in the full app context."

Step 3: Analyze Requirements

Read and analyze all three files:

1. **spec.md** - Understand the user flows and UI requirements 2. **data.json** - Understand the data structure and sample content 3. **types.ts** - Understand the TypeScript interfaces and available callbacks

Identify what views are needed based on the spec. Common patterns:

• List/dashboard view (showing multiple items)
• Detail view (showing a single item)
• Form/create view (for adding/editing)

Step 4: Clarify the Screen Design Scope

If the spec implies multiple views, use the AskUserQuestion tool to confirm which view to build first:

"The specification suggests a few different views for **[Section Title]**:

1. **[View 1]** - [Brief description] 2. **[View 2]** - [Brief description]

Which view should I create first?"

If there's only one obvious view, proceed directly.

Step 5: Invoke the Frontend Design Skill

Before creating the screen design, read the `frontend-design` skill to ensure high-quality design output.

Read the file at `.claude/skills/frontend-design/SKILL.md` and follow its guidance for creating distinctive, production-grade interfaces.

Step 6: Create the Props-Based Component

Create the main component file at `src/sections/[section-id]/components/[ViewName].tsx`.

Component Structure

The component MUST:

• Import types from the types.ts file
• Accept all data via props (never import data.json directly)
• Accept callback props for all actions
• Be fully self-contained and portable

Example:

import type { InvoiceListProps } from '@/../product/sections/[section-id]/types'

export function InvoiceList({
  invoices,
  onView,
  onEdit,
  onDelete,
  onCreate
}: InvoiceListProps) {
  return (
    <div className="max-w-4xl mx-auto">
      {/* Component content here */}

      {/* Example: Using a callback */}
      <button onClick={onCreate}>Create Invoice</button>

      {/* Example: Mapping data with callbacks */}
      {invoices.map(invoice => (
        <div key={invoice.id}>
          <span>{invoice.clientName}</span>
          <button onClick={() => onView?.(invoice.id)}>View</button>
          <button onClick={() => onEdit?.(invoice.id)}>Edit</button>
          <button onClick={() => onDelete?.(invoice.id)}>Delete</button>
        </div>
      ))}
    </div>
  )
}

Design Requirements

• **Mobile responsive:** Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) and ensure the design layout works gracefully on mobile, tablet and desktop screen sizes.
• **Light & dark mode:** Use `dark:` variants for all colors
• **Use design tokens:** If defined, apply the product's color palette and typography
• **Follow the frontend-design skill:** Create distinctive, memorable interfaces

Applying Design Tokens

**If `/product/design-system/colors.json` exists:**

• Use the primary color for buttons, links, and key accents
• Use the secondary color for tags, highlights, secondary elements
• Use the neutral color for backgrounds, text, and borders
• Example: If primary is `lime`, use `lime-500`, `lime-600`, etc. for primary actions

**If `/product/design-system/typography.json` exists:**

• Note the font choices for reference in comments
• The fonts will be applied at the app level, but use appropriate font weights

**If design tokens don't exist:**

• Fall back to `stone` for neutrals and `lime` for accents (Design OS defaults)

What to Include

• Implement ALL user flows and UI requirements from the spec
• Use the prop data (not hardcoded values)
• Include realistic UI states (hover, active, etc.)
• Use the callback props for all interactive elements
• Handle optional callbacks with optional chaining: `onClick={() => onDelete?.(id)}`

What NOT to Include

• No `import data from` statements - data comes via props
• No features not specified in the spec
• No routing logic - callbacks handle navigation intent
• No navigation elements (shell handles navigation)

Step 7: Create Sub-Components (If Needed)

For complex views, break down into sub-