Krow-workspace/.claude/skills/krow-paper-design/SKILL.md

---
name: krow-paper-design
description: KROW Paper design file conventions covering design tokens, component patterns, screen structure, and naming rules. Use this when creating or updating screens in the Paper design tool, auditing designs for token compliance, building new flows, or restructuring existing frames. Ensures visual consistency across all Paper design files for the KROW staff and client apps.
---

# KROW Paper Design Conventions

This skill defines the design token system, component patterns, screen structure conventions, and workflow rules established for the KROW Design Revamp Paper file. All design work in Paper must follow these conventions.

## When to Use This Skill

- Creating new screens or flows in Paper
- Updating existing frames to match the design system
- Auditing designs for token compliance
- Adding components (buttons, chips, inputs, badges, cards)
- Structuring shift detail pages, onboarding flows, or list screens
- Setting up navigation patterns (back buttons, bottom nav, CTAs)
- Reviewing Paper designs before handoff to development

## 1. Design Tokens

### Color Palette

**Primary:**
| Token | Hex | Usage |
|-------|-----|-------|
| Background | `#FAFBFC` | Page/artboard background |
| Foreground | `#121826` | Headings, primary text, dark UI elements |
| Primary | `#0A39DF` | CTAs, active states, links, selected chips, nav active icons, pay rates |
| Primary Fg | `#F7FAFC` | Light foreground on primary surfaces |

**Semantic:**
| Token | Hex | Usage |
|-------|-----|-------|
| Secondary | `#F1F3F5` | Subtle backgrounds, dividers, secondary button bg |
| Accent | `#F9E547` | Highlight, warning chip accents |
| Text Secondary | `#6A7382` | Labels, captions, inactive nav, section headers, back chevrons |
| Destructive | `#F04444` | Error states, destructive actions |

**Border & Input:**
| Token | Hex | Usage |
|-------|-----|-------|
| Border | `#D1D5DB` | Card borders, unselected chip borders, outline button borders |
| Input | `#F5F6F8` | Text input background (read-only/disabled states) |

**Status:**
| Token | Hex | Usage |
|-------|-----|-------|
| Success | `#10B981` | Accept buttons, active status, checkmarks |
| Info | `#0A39DF` | Informational badges (same as Primary) |
| Warning | `#D97706` | Urgent/Pending badge text |
| Neutral | `#94A3B8` | Disabled text, placeholder text |
| Danger | `#F04444` | Error badges, destructive (same as Destructive) |

**Gradients:**
| Token | Definition | Usage |
|-------|-----------|-------|
| mobileHero | Foreground → Primary → Primary Fg | Hero sections, splash screens |
| adminHero | Primary → Success | Admin/dashboard hero cards |

### Semantic Badge Colors

| Badge | Background | Text Color |
|-------|-----------|------------|
| Active | `#ECFDF5` | `#059669` |
| Confirmed | `#EBF0FF` | `#0A39DF` |
| Pending | `#FEF9EE` | `#D97706` |
| Urgent | `#FEF9EE` | `#D97706` |
| One-Time | `#ECFDF5` | `#059669` |
| Recurring | `#EFF6FF` | `#0A39DF` |

### Typography

**Inter Tight — Headings:**
| Style | Size | Weight | Letter Spacing | Line Height | Usage |
|-------|------|--------|---------------|-------------|-------|
| Display | 28px | 700 | -0.02em | 34px | Page titles (Find Shifts, My Shifts) |
| Heading 1 | 24px | 700 | -0.02em | 30px | Detail page titles (venue names) |
| Heading 2 | 20px | 700 | -0.01em | 26px | Section headings |
| Heading 3 | 18px | 700 | -0.01em | 22px | Card titles, schedule values |
| Heading 4 | 16px | 700 | — | 20px | Card titles (standard cards), sub-headings |

**Manrope — Body:**
| Style | Size | Weight | Line Height | Usage |
|-------|------|--------|-------------|-------|
| Body Large Regular | 16px | 400 | 20px | Long body text |
| Body Large Medium | 16px | 500 | 20px | Emphasized body text |
| Body Large Semibold | 16px | 600 | 20px | Strong labels, Full Width CTA text (15px) |
| Body Default | 14px | 400 | 18px | Body text, descriptions |
| Body Default Semibold | 14px | 600 | 18px | Button text, chip text, bold body |
| Caption | 12px | 400 | 16px | Small text, helper text, input labels |
| Overline Label | 11px | 600 | 14px | Uppercase section headers (letter-spacing: 0.06em) |
| Badge Text | 11px | 600-700 | 14px | Status badge labels (letter-spacing: 0.04em) |
| Nav Label | 10px | 600 | 12px | Bottom nav labels |

### Spacing Scale

| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Tight spacing (subtitle under title) |
| sm | 8px | Element gap within groups |
| md | 12px | Group gap (label to input) |
| lg | 16px | Card padding, medium section gap |
| xl | 24px | Page margins, section gap |
| 2xl | 32px | Large section separation |

**Page Layout:**
| Token | Value |
|-------|-------|
| Page margins | 24px |
| Section gap | 24px |
| Card padding | 16px |
| Element gap | 8-12px |
| Background | `#FAFBFC` |
| Bottom safe area | 40px |

### Border Radii

| Token | Value | Usage |
|-------|-------|-------|
| sm | 8px | Small chips, badges, status pills |
| md | 12px | Cards, inputs, list row containers, data rows |
| lg | 18px | Hero cards, gradient cards |
| xl | 24px | Large containers |
| pill | 999px | Progress bar segments only |

### Icon Sizes

Standard sizes: 16, 20, 24, 32dp

## 2. Component Patterns

### Buttons

All buttons: radius 14px, padding 12px/24px, text Manrope 14px/600

**Primary:**
- Background: `#0A39DF`, text: `#FFFFFF`

**Secondary:**
- Background: `#F1F3F5`, border: 1.5px `#D1D5DB`, text: `#121826`

**Destructive:**
- Background: `#F04444`, text: `#FFFFFF`

**Disabled:**
- Background: `#F1F3F5`, no border, text: `#94A3B8`

**Accept:**
- Background: `#10B981`, text: `#FFFFFF`

**Dark:**
- Background: `#121826`, text: `#FFFFFF`

**Full Width CTA:**
- Same as Primary but `width: 100%`, padding 14px/24px, text Manrope 15px/600

**Back Icon Button (Bottom CTA):**
- 52x52px square, border: 0.5px `#D1D5DB`, radius: 14px, background: `#FFFFFF`
- Contains chevron-left SVG (20x20, viewBox 0 0 24 24, stroke `#121826`, strokeWidth 2)
- Path: `M15 18L9 12L15 6`

### Chips

All chips: border 1.5px, text Manrope 14px/600, gap 8px for icon+text

**Default (Large) - for role/skill selection:**
- Selected: bg `#EFF6FF`, border `#0A39DF`, radius 10px, padding 12px/16px
  - Checkmark icon (14x14, stroke `#0A39DF`), text `#0A39DF`
- Unselected: bg `#FFFFFF`, border `#6A7382`, radius 10px, padding 12px/16px
  - Text Manrope 14px/500 `#6A7382`

**Warning Chips:**
- Selected: bg `#F9E5471A`, border `#E6A817`, radius 10px, padding 12px/16px
  - Checkmark icon (stroke `#E6A817`), text `#E6A817`
- Unselected: bg `#FFFFFF`, border `#F0D78C`, radius 10px, padding 12px/16px
  - Text `#E6A817`

**Error Chips:**
- Selected: bg `#FEF2F2`, border `#F04444`, radius 10px, padding 12px/16px
  - Checkmark icon (stroke `#F04444`), text `#F04444`
- Unselected: bg `#FFFFFF`, border `#FECACA`, radius 10px, padding 12px/16px
  - Text `#F04444`

**Small - for tabs, filters:**
- Selected: bg `#EFF6FF`, border 1.5px `#0A39DF`, radius 8px, padding 6px/12px
  - Checkmark icon (12x12), text Manrope 12px/600 `#0A39DF`
- Unselected: bg `#FFFFFF`, border 1.5px `#D1D5DB`, radius 8px, padding 6px/12px
  - Text Manrope 12px/500 `#6A7382`
- Active (filled): bg `#0A39DF`, radius 8px, padding 6px/12px
  - Text Manrope 12px/600 `#FFFFFF`

**Status Badges:**
- Radius: 8px, padding: 4px/8px
- Text: Manrope 11px/600-700, uppercase, letter-spacing 0.04em
- Colors follow semantic badge table above

### Text Inputs

- Border: 1.5px `#E2E8F0`, radius: 12px, padding: 12px/14px
- Background: `#FFFFFF`
- Placeholder: Manrope 14px/400, color `#94A3B8`
- Filled: Manrope 14px/400, color `#111827`
- Label above: Manrope 12px/500:
  - Default/filled: color `#94A3B8`
  - Filled with value: color `#6A7382`
  - Focused: color `#0A39DF`
  - Error: color `#F04444`
  - Disabled: color `#94A3B8`
- Focused: border color `#0A39DF`, border-width 2px
- Error: border color `#F04444`, border-width 2px, background `#FEF2F2`
- Error helper text: Manrope 12px/400, color `#F04444`

### Border Width

- **Standard border width: `0.5px`** — All card borders, dividers, and outline buttons use `0.5px` unless explicitly stated otherwise.
- **Text inputs: `1.5px`** — To ensure visibility and distinction from card borders.
- **Chips: `1.5px`** — All chip variants (default, warning, error, small).
- **Secondary buttons: `1.5px`** — Outline/secondary button borders.

### Cards

**Standard Card:**
- Background: `#FFFFFF`, border: 0.5px `#D1D5DB`, radius: 12px, padding: 16px
- Title: Inter Tight 16px/700 `#121826`
- Body: Manrope 14px/400 `#6A7382`
- Gap: 8px between title and body

**Hero / Gradient Card:**
- Radius: 18px, padding: 20px, gap: 6px
- Background: gradient (mobileHero or adminHero)
- Label: Manrope 12px/400 `#FFFFFFB3` (white 70%)
- Value: Inter Tight 28px/700 `#FFFFFF`
- Sub-text: Manrope 12px/400 `#FFFFFF99` (white 60%)

**List Rows (grouped):**
- Container: radius 12px, border 0.5px `#D1D5DB`, background `#FFFFFF`, overflow clip
- Row: padding ~16px, gap between text elements 2px
- Row title: Manrope 14px/600 `#121826`
- Row subtitle: Manrope 13px/400 `#6A7382`
- Row divider: 1px `#D1D5DB` (between rows, not on last)
- Chevron: `›` or SVG, `#6A7382`

**Data Row:**
- Background: `#F1F3F5`, radius: 12px, padding: 12px
- Label: Manrope 11px/400 `#6A7382`
- Value: Inter Tight 20px/700 `#121826`
- Layout: flex row, equal width columns, gap 8px

### Contact/Info Rows

- Container: radius 12px, border 0.5px `#D1D5DB`, background `#FFFFFF`, overflow clip
- Row: padding 13px/16px, gap 10px, border-bottom 0.5px `#F1F3F5` (except last)
- Icon: 16px, stroke `#6A7382`
- Label: Manrope 13px/500 `#6A7382`, width 72px fixed
- Value: Manrope 13px/500 `#121826` (or `#0A39DF` for phone/links)

### Section Headers

- Text: Manrope 11px/600, uppercase, letter-spacing 0.06em, color `#6A7382`
- Gap to content below: 10px

## 3. Screen Structure

### Artboard Setup

- Width: 390px (iPhone standard)
- Height: 844px (default), or `fit-content` for scrollable detail pages
- Background: `#FAFBFC`
- Flex column layout, overflow: clip

### Frame Naming Convention

```
<app>-<section>-<screen_number>-<screen_name>
```

Examples:
- `staff-1-1-splash`
- `staff-2-3-personal-information`
- `staff-4-1-my-shifts`
- `staff-5-2-shift-details`
- `shift-5-3-confirmation`

Section headers use: `<number> - <Section Name>` (e.g., `4 - My Shifts`)

### Status Bar

- Height: 44px, full width (390px)
- Left: "9:41" text (system font)
- Right: Signal, WiFi, Battery SVG icons (68px wide)

### Header Back Button

- Placed below status bar in a combined "Status Bar + Back" frame (390x72px)
- Chevron SVG: 20x20, viewBox 0 0 24 24, stroke `#6A7382`, strokeWidth 2
- Path: `M15 18L9 12L15 6`
- Back button frame: 390x28px, padding-left: 24px

### Progress Bar (Onboarding)

- Container: 342px wide (24px margins), 3px height segments
- Segments: pill radius (999px), gap between
- Filled: `#0A39DF`, Unfilled: `#F1F3F5`

### Bottom CTA Convention

- Pinned to bottom using `marginTop: auto` on the CTA container
- Layout: flex row, gap 12px, padding 0 24px
- Back button: 52x52px icon-only button with chevron-left (stroke `#121826`)
- Primary CTA: flex 1, height 52px, radius 14px, bg `#0A39DF`
- Bottom safe padding: 40px (on artboard paddingBottom)

### Bottom Navigation Bar

- Full width, padding: 10px top, 28px bottom
- Border-top: 1px `#F1F3F5`, background: `#FFFFFF`
- 5 items: Home, Shifts, Find, Payments, Profile
- Active: icon stroke `#0A39DF`, label Manrope 10px/600 `#0A39DF`
- Inactive: icon stroke `#6A7382`, label Manrope 10px/600 `#6A7382`
- Active icon may have light fill (e.g., `#EBF0FF` on calendar/search)

## 4. Screen Templates

### List Screen (My Shifts, Find Shifts)

```
Artboard (390x844, bg #FAFBFC)
  Status Bar (390x44)
  Header Section
    Page Title (Display: Inter Tight 28px/700)
    Tab/Filter Chips (Small chip variant)
  Content
    Date Header (Section label style, uppercase)
    Shift Cards (12px radius, 1px border #D1D5DB)
  Bottom Nav Bar
```

### Detail Screen (Shift Details)

```
Artboard (390x fit-content, bg #FAFBFC)
  Status Bar (390x44)
  Header Bar (Back chevron + "Shift Details" title + share icon)
  Badges Row (status chips)
  Role Title (H1) + Venue (with avatar)
  Schedule/Pay Cards (two-column)
  Job Description (section label + body text)
  Location (card with map + address)
  Requirements (section label + checkmark list)
  Shift Contact (section label + contact card with rows)
  [Optional] Note from Manager (warm bg card)
  Bottom CTA (pinned)
```

### Onboarding Screen

```
Artboard (390x844, bg #FAFBFC, justify: flex-start, paddingBottom: 40px)
  Status Bar + Back (390x72)
  Progress Bar (342px, 3px segments)
  Step Counter ("Step X of Y" - Body Small)
  Page Title (H1: Inter Tight 24px/700)
  [Optional] Subtitle (Body Default)
  Form Content (inputs, chips, sliders)
  Bottom CTA (marginTop: auto - back icon + Continue)
```

### Confirmation Screen

```
Artboard (390x844, bg #FAFBFC)
  Status Bar
  Centered Content
    Success Icon (green circle + checkmark)
    Title (Display: Inter Tight 26px/700, centered)
    Subtitle (Body Default, centered, #6A7382)
    Details Card (border #D1D5DB, rows with label/value pairs)
  Bottom CTAs (primary + outline)
```

## 5. Workflow Rules

### Write Incrementally

Each `write_html` call should produce ONE visual group:
- A header, a card, a single list row, a button bar, a section
- Never batch an entire screen in one call

### Review Checkpoints

After every 2-3 modifications, take a screenshot and evaluate:
- **Spacing**: Uneven gaps, cramped groups
- **Typography**: Hierarchy, readability, correct font/weight
- **Contrast**: Text legibility, element distinction
- **Alignment**: Vertical lanes, horizontal alignment
- **Clipping**: Content cut off at edges
- **Token compliance**: All values match design system tokens

### Color Audit Process

When updating frames to match the design system:
1. Get computed styles for all text, background, border elements
2. Map old colors to design system tokens:
   - Dark navy (`#0F4C81`, `#1A3A5C`) -> Primary `#0A39DF`
   - Near-black (`#111827`, `#0F172A`) -> Foreground `#121826`
   - Gray variants (`#94A3B8`, `#64748B`, `#475569`) -> Text Secondary `#6A7382`
   - Green accents (`#20B486`) -> Primary `#0A39DF` (for pay) or `#059669` (for status)
3. Batch update using `update_styles` with multiple nodeIds per style change
4. Verify with screenshots

### Structural Consistency

When creating matching screens (e.g., two shift detail views):
- Use identical section ordering
- Match section header styles (11px/700 uppercase `#6A7382`)
- Use same card/row component patterns
- Maintain consistent padding and gap values

## 6. SVG Icon Patterns

### Chevron Left (Back)
```html
<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
  <path d="M15 18L9 12L15 6" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
```

### Map Pin
```html
<svg width="18" height="18" viewBox="0 0 24 24" fill="none">
  <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
  <circle cx="12" cy="10" r="3" stroke="#6A7382" stroke-width="2"/>
</svg>
```

### User (Supervisor)
```html
<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
  <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
  <circle cx="12" cy="7" r="4" stroke="#6A7382" stroke-width="2"/>
</svg>
```

### Phone
```html
<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
  <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.127.96.361 1.903.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0 1 22 16.92z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
```

### Checkmark (Requirement Met)
```html
<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
  <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
  <path d="M22 4L12 14.01l-3-3" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
```

### Chip Checkmark
```html
<!-- Large chip (14x14) -->
<svg width="14" height="14" viewBox="0 0 14 14" fill="none">
  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
</svg>

<!-- Small chip (12x12) -->
<svg width="12" height="12" viewBox="0 0 14 14" fill="none">
  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
```

## 7. Anti-Patterns

### Colors
- Never use `#0F4C81`, `#1A3A5C` (old navy) - use `#0A39DF` (Primary)
- Never use `#111827`, `#0F172A` - use `#121826` (Foreground)
- Never use `#94A3B8`, `#64748B`, `#475569` - use `#6A7382` (Text Secondary)
- Never use `#20B486` for pay rates - use `#0A39DF` (Primary)
- Never use `#E2E8F0` for card borders - use `#D1D5DB` (Border)

### Components
- Never use pill radius (999px) for chips or badges - use 8px or 10px
- Never use gradient backgrounds on buttons
- Never mix font families within a role (headings = Inter Tight, body = Manrope)
- Never place back buttons at the bottom of frames - always after status bar
- Never hardcode CTA position - use `marginTop: auto` for bottom pinning

### Structure
- Never batch an entire screen in one `write_html` call
- Never skip review checkpoints after 2-3 modifications
- Never create frames without following the naming convention
- Never use `justifyContent: space-between` on artboards with many direct children - use `marginTop: auto` on the CTA instead

## Summary

**The design file is the source of truth for visual direction.** Every element must use the established tokens:

1. **Colors**: 7 core tokens + semantic badge colors
2. **Typography**: Inter Tight (headings) + Manrope (body), defined scale
3. **Spacing**: 24px page padding, 16-24px section gaps, 40px bottom safe area
4. **Radii**: 8px (chips/badges), 12px (cards/inputs), 14px (buttons/CTAs)
5. **Components**: Buttons, chips (large/small), inputs, cards, badges, nav bars
6. **Structure**: Status bar > Back > Content > Bottom CTA (pinned)
7. **Naming**: `<app>-<section>-<number>-<name>`

When in doubt, screenshot an existing screen and match its patterns exactly.