@fresh-ds/recipes

Screen-level composition blocks for React Native and Expo. Recipes compose lower-level components from @fresh-ds/ui into higher-order patterns that PMs, designers, and engineers use to scaffold screens quickly.

Purpose

Use recipes when you need:

• Screen blocks — Page headers, section cards, empty states, sticky footers
• Prototyping primitives — Higher-level than raw components, faster to compose
• Consistent composition — Patterns engineering can implement from easily
• Designer/PM surface — Better prompting and ideation than components alone

Use @fresh-ds/ui when you need lower-level building blocks or custom compositions.

Available Recipes (12)

| Recipe | Purpose | | --------------------- | ----------------------------------------------- | | EmptyState | Zero-state screens with icon, title, and action | | FormField | Label + input + error message composition | | PageHeader | Screen title with optional actions and metadata | | ProductChip | Compact product representation | | QuantityStepper | Numeric stepper with min/max | | SectionCard | Grouped content with header and actions | | SectionHeader | Section divider with title and actions | | SelectionCard | Tappable selection with selected state | | SignalCard | Status/alert card with icon and message | | StickyActionFooter | Fixed bottom action bar | | SummaryCard | Data summary with label-value pairs | | TreatmentDetailCard | Treatment-specific detail view |

Usage

import { PageHeader, SectionCard, StickyActionFooter } from '@fresh-ds/recipes';

function MyScreen() {
  return (
    <Stack gap="4">
      <PageHeader title="Patient Details" subtitle="Jane Doe • 34 years" />
      <SectionCard title="Contact Information" onEdit={() => {}}>
        <DataField label="Email" value="[email protected]" />
        <DataField label="Phone" value="+1 555-0123" />
      </SectionCard>
      <StickyActionFooter primaryLabel="Save" onPrimaryPress={() => {}} />
    </Stack>
  );
}

Layering

Recipes compose components from @fresh-ds/ui, which compose primitives from @fresh-ds/ui:

Recipe (PageHeader)
  └── Component (Stack, Text, Button, Icon)
        └── Primitive (Box, Pressable, Text as FreshText)
              └── Token (color, spacing, radius)

Structure

platforms/react-native/recipes/
  src/
    index.ts                    # Public exports
    PageHeader/
      PageHeader.tsx            # Implementation
      PageHeader.manifest.json  # API contract
      PageHeader.stories.tsx    # Storybook stories
    SectionCard/
    ...

Manifests

Each recipe has a manifest defining its API:

{
  "name": "PageHeader",
  "props": [
    { "name": "title", "type": "string", "required": true },
    { "name": "subtitle", "type": "string" },
    { "name": "onBack", "type": "function" }
  ]
}

Manifests are authored here, then synced to contract/manifests/:

npm run sync:manifests

Verification

# Typecheck
npm run typecheck --workspace @fresh-ds/recipes

# Run tests
npm run test --workspace @fresh-ds/recipes

# Build
npm run build --workspace @fresh-ds/recipes

# Check showcase
npm run dev:showcase  # Verify recipes render correctly

What Belongs Here

• Screen-level composition components
• Recipe manifests (authoritative source)
• Recipe stories and examples
• Recipe-specific tests

What Does NOT Belong Here

• Atomic components — lives in platforms/react-native/ui/
• Primitives — lives in platforms/react-native/ui/src/primitives/
• App screens — lives in apps/showcase/ or product repos
• Design system tokens — lives in contract/tokens/

Agent Guidance

When working with recipes:

• Start with recipes for screen scaffolding — fall back to components for custom needs
• Use semantic token strings — gap="4" not gap={16}
• Don't duplicate recipes — if a pattern repeats, extend or parameterize the existing recipe
• Ship with manifest — every recipe needs a .manifest.json
• Test in showcase — add stories to verify visual output

Recipe vs Component Decision

| Need | Use | | ----------------------------------- | --------- | | Screen scaffolding, common patterns | Recipe | | Custom layout, novel composition | Component | | One-off, single-use | Component | | Repeated across multiple screens | Recipe |

Related

| Doc | Purpose | | -------------------------------- | ---------------------------- | | ../ui/README.md | Component layer | | ../ui/src/primitives/ | Primitive layer | | ../../docs/usage-guidelines.md | Layer selection guidance | | ../../docs/screen-patterns.md | Screen composition templates |