web-frontend

This skill provides guidance for developing frontend components in the /web project for CRAN/E, a PWA that searches CRAN packages and authors.

Tech Stack

• TypeScript for type safety
• React Router v7 (Vite build) with Remix-style file-based routes
• Tailwind CSS with Radix Colors for styling
• CVA (Class Variance Authority) for component variants
• Remix Icons (@remixicon/react) for icons
• Supabase for data fetching via typed client

Design Principles

Minimal & Professional

The design follows a clean, minimal aesthetic with:

• Gradient accents (iris, ruby, jade, bronze, sand, amethyst, opal)
• Subtle hover effects with slow transitions (duration-700)
• Rounded corners (rounded-full for pills, rounded-xl for cards)
• Consistent spacing using Tailwind's gap utilities
• Dark mode support via Radix Colors

Component Structure

All UI components follow these patterns:

1. Props Definition: Use PropsWithChildren when accepting children, combine with VariantProps<typeof twBase> from CVA
2. CVA Styling: Define variants using cva() for reusable, type-safe class composition
3. Display Name: Always set Component.displayName for debugging
4. Type Safety: Leverage TypeScript for props, Zod schemas for validation

Core Component Patterns

Layout Components

Header (app/modules/header.tsx):

• Gradient backgrounds with variants
• Headline + optional subline structure
• Optional ornament slot for additional content

PageContent (app/modules/page-content.tsx):

• Full-width wrapper with consistent padding
• full-width class for spanning viewport width
• Inner flex column with gap-16 for section spacing

PageContentSection (app/modules/page-content-section.tsx):

• Headline, subline, and fragment ID for anchor navigation
• Prose variant for long-form text styling
• Gap-16 for consistent vertical rhythm

Interactive Components

InfoPill (app/modules/info-pill.tsx):

• Rounded-full border with gradient hover effects
• Optional label slot (left-aligned, gray-dim)
• Size variants: xs, sm, md, lg
• Gradient variants matching design system
• Hover opacity transition on gradient overlay

InfoCard (app/modules/info-card.tsx):

• Rounded-xl border with gradient hover effects
• Min height for consistent card sizing
• Icon indicators (external/internal) with wiggle animation on hover
• Group hover states for coordinated animations

Tag (app/modules/tag.tsx):

• Small, uppercase, rounded-full labels
• Border gradients (iris, jade) for semantic meaning
• Size variants: xs, sm

Utility Components

Separator (app/modules/separator.tsx):

• Simple <hr> with opacity-20 for subtle dividers

Prose (app/modules/prose.tsx):

• Typography component for long-form content
• Supports dangerouslySetInnerHTML for rendered HTML
• Text-xl, font-light, leading-normal baseline

Anchors & AnchorLink (app/modules/anchors.tsx):

• Navigation for in-page sections
• Fragment-based routing

Color System

Use Radix Colors with semantic variants:

• iris: Primary/action color
• ruby: Error/destructive actions
• jade: Success/positive states
• bronze: Neutral/informational
• sand/gold: Warm highlights
• amethyst: Secondary accent (plum + iris mix)
• opal: Cool accent (iris + sky mix)

Text colors:

• text-gray-normal: Body text
• text-gray-dim: Secondary/muted text
• text-gray-12/text-gray-4: Prose (dark/light mode)

Page Structure Pattern

Reference pages follow this structure:

1. Header with gradient and title
2. Anchors navigation (if multiple sections)
3. PageContent wrapper
4. PageContentSection for each major section
5. Separator between sections

Example from _page.privacy._index.tsx:

<Header gradient="sand" headline="Privacy" subline="..." />
<Anchors anchorIds={...}>...</Anchors>
<PageContent>
  <PageContentSection headline="General" fragment="general">
    <p>...</p>
  </PageContentSection>
  <Separator />
  <PageContentSection headline="..." fragment="...">
    ...
  </PageContentSection>
</PageContent>

Route Patterns

• _page.* files: Public pages with layout wrapper
• _page.package.$packageName.tsx: Package detail pages
• _page.author.$authorName.tsx: Author profile pages
• _page.privacy._index.tsx: Static content pages
• api.*: API endpoints (search, MCP)
• *.og.*: Open Graph image generation

Data Loading

Use React Router's loader pattern:

export const loader: LoaderFunction = async ({ params }) => {
  const data = await Service.fetchData(params.id);
  if (!data) throw data(null, { status: 404 });
  return data(data);
};

Access via useLoaderData<LoaderData>().

Meta Tags

Use mergeMeta() helper for combining meta tags:

export const meta = mergeMeta(({ data }) => {
  const title = `${data.name} | CRAN/E`;
  return [
    { title },
    { name: "description", content: data.description },
    { property: "og:title", content: title },
    { property: "og:image", content: `${url}/og` },
  ];
});

Styling Best Practices

1. Use CVA for variants: Don't hardcode conditional classes
2. Prefer Tailwind utilities: Avoid custom CSS when possible
3. Dark mode: Use Radix Colors with dark: variants
4. Transitions: Use duration-700 for smooth, professional animations
5. Responsive: Use md: breakpoint for desktop adjustments
6. Spacing: Use gap utilities for flex/grid spacing instead of margins

Accessibility

• Use semantic HTML elements
• Provide meaningful alt text for images
• Ensure keyboard navigation works
• Test with screen readers when adding interactive elements

Icon Usage

Import from @remixicon/react:

import { RiArrowRightSLine, RiExternalLinkLine } from "@remixicon/react";

Size prop for consistency (typically 16 or 20).

Component File Structure

import { cva, VariantProps } from "cva";
import { PropsWithChildren, ReactNode } from "react";

type Props = PropsWithChildren<
  VariantProps<typeof twBase> & {
    // Custom props
  }
>;

const twBase = cva({
  base: "...",
  variants: {
    size: { ... },
  },
  defaultVariants: { ... },
});

export function Component(props: Props) {
  const { children, ...rest } = props;
  return <div className={twBase(rest)}>{children}</div>;
}

Component.displayName = "Component";

Testing Strategy

• Lint: npm run lint from /web
• Typecheck: npm run typecheck from /web
• Build: npm run build from /web
• No unit tests; validation relies on lint/typecheck/build

Common Patterns to Follow

Example: Package Detail Page (_page.package.$packageName.tsx)

• Header with package name and gradient
• Anchors for section navigation (Synopsis, Documentation, Team, Insights, Binaries, Dependencies)
• Multiple PageContentSection components
• InfoPill for metadata (version, license, etc.)
• InfoCard for related packages/authors
• ExternalLink components for CRAN URLs
• Lazy-loaded components for performance (e.g., PackageDependencySearch)

Example: Author Page (_page.author.$authorName.tsx)

• Header with author name
• List of packages by author using InfoCard grid
• Team section showing collaborators
• Similar structure to package page

File Organization

• Routes: /web/app/routes/*.tsx
• Components: /web/app/modules/*.tsx
• Data services: /web/app/data/*.ts
• Types: /web/app/data/*.shape.ts (Zod schemas), *.types.generated.ts (Supabase)

Environment

• Node >= 20 (v23.3.0 recommended via .nvmrc)
• npm (with legacy-peer-deps = true in .npmrc)
• Required env vars: See .env.example