FPKit Developer

A Claude Code skill for building applications with @fpkit/acss components.

Purpose

This skill helps developers:

•Compose custom components from fpkit primitives
•Validate CSS variables against fpkit conventions
•Maintain accessibility when building with fpkit
•Follow best practices for component composition

This skill is for: Developers using @fpkit/acss in their applications

Not for: Developing the @fpkit/acss library itself (use fpkit-component-builder for that)

Workflow

When a user requests a new component or feature, follow this workflow:

Step 1: Analyze the Request

Understand what the user needs:

•What is the component supposed to do?
•What user interactions are required?
•Are there similar fpkit components?

Ask clarifying questions if the requirements are unclear.

Step 2: Check for Existing fpkit Components

Review the @fpkit/acss component catalog or Storybook:

Available components:

•Buttons: Button (with aria-disabled pattern, focus management, performance optimized)
•Links: Link (auto security for external links, ref forwarding, prefetch support)
•Cards: Card, CardHeader, CardTitle, CardContent, CardFooter
•Forms: Input, Field, FieldLabel, FieldInput
•Layout: Header, Main, Footer, Aside, Nav
•Typography: Heading, Text
•Dialogs: Dialog, Modal
•Feedback: Alert, Badge, Tag
•Data: Table, List
•Interactive: Details, Popover
•Icons: Icon library

Decision tree:

code

1. CHECK: Does fpkit have the exact component?
   ✓ YES → Use it directly, customize with CSS variables
           (Skip to Step 6: Accessibility)
   ✗ NO  → Continue to next check

2. CHECK: Can it be built by composing 2+ fpkit components?
   ✓ YES → Proceed to Step 3 (Composition)
   ✗ NO  → Continue to next check

3. CHECK: Can an existing fpkit component be extended/wrapped?
   ✓ YES → Proceed to Step 4 (Extension)
   ✗ NO  → Continue to next check

4. BUILD: Component requires custom implementation
   → Proceed to Step 5 (Custom Implementation)

Step 3: Compose from fpkit Components

Create a new component file that imports and combines fpkit components:

tsx

// components/StatusButton.tsx
import { Button, Badge } from '@fpkit/acss'

export interface StatusButtonProps extends React.ComponentProps<typeof Button> {
  status: 'active' | 'inactive' | 'pending'
}

export const StatusButton = ({ status, children, ...props }: StatusButtonProps) => {
  return (
    <Button {...props}>
      {children}
      <Badge variant={status}>{status}</Badge>
    </Button>
  )
}

Guidelines:

•Import fpkit components using named imports
•Extend fpkit component prop types with TypeScript
•Spread ...props to preserve all fpkit functionality
•Keep composition simple (≤ 3 levels deep)

Reference: See references/composition.md for patterns and examples

Step 4: Extend fpkit Components

Wrap an fpkit component to add custom behavior:

tsx

// components/LoadingButton.tsx
import { Button, type ButtonProps } from '@fpkit/acss'
import { useState } from 'react'

export interface LoadingButtonProps extends ButtonProps {
  loading?: boolean
  onClickAsync?: (e: React.MouseEvent) => Promise<void>
}

export const LoadingButton = ({
  loading,
  onClickAsync,
  children,
  ...props
}: LoadingButtonProps) => {
  const [isLoading, setIsLoading] = useState(loading)

  const handleClick = async (e: React.MouseEvent) => {
    if (onClickAsync) {
      setIsLoading(true)
      try {
        await onClickAsync(e)
      } finally {
        setIsLoading(false)
      }
    }
  }

  return (
    <Button
      {...props}
      disabled={isLoading || props.disabled}
      onClick={handleClick}
    >
      {isLoading ? 'Loading...' : children}
    </Button>
  )
}

Guidelines:

•Extend fpkit prop types (don't replace them)
•Preserve all fpkit functionality (aria-disabled, focus management, etc.)
•Add custom logic around fpkit components
•
Maintain accessibility - fpkit Button automatically handles:
- •aria-disabled pattern for better keyboard accessibility
- •Focus management (stays in tab order when disabled)
- •Event prevention when disabled
- •Automatic className merging for .is-disabled styling

Step 5: Custom Implementation

If the component is truly custom and can't use fpkit:

•
Follow fpkit patterns:
- •Use semantic HTML
- •Add proper ARIA attributes
- •Support keyboard navigation
- •Use rem units (not px)
- •Define CSS variables for theming

•

Create styles (if needed):

scss

// components/CustomComponent.scss
.custom-component {
  padding: var(--custom-padding, 1rem);
  border-radius: var(--custom-radius, 0.375rem);
  background: var(--custom-bg, white);

  // Use rem units only!
  margin-bottom: 1rem;  // NOT 16px
  gap: 0.5rem;           // NOT 8px
}

•

Validate CSS variables (for custom styles):

bash

python scripts/validate_css_vars.py components/

Reference: See references/css-variables.md for naming conventions

Step 6: Ensure Accessibility

Check accessibility compliance:

• Uses semantic HTML (<button>, <nav>, etc.)
• All interactive elements are keyboard accessible
• Proper ARIA attributes (aria-label, aria-describedby, etc.)
• Visible focus indicators
• Color contrast meets WCAG AA (4.5:1 for normal text)
• Screen reader friendly (meaningful labels)

Test:

•Navigate with keyboard only (Tab, Enter, Escape)
•Use automated testing (jest-axe)
•Check Storybook a11y addon (if documenting in Storybook)

Reference: See references/accessibility.md for patterns

Step 7: Document the Component (Optional)

When creating a reusable component for a team:

Create a Storybook story:

tsx

// components/StatusButton.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { StatusButton } from './StatusButton'

const meta = {
  title: 'Components/StatusButton',
  component: StatusButton,
  tags: ['autodocs'],
} satisfies Meta<typeof StatusButton>

export default meta
type Story = StoryObj<typeof meta>

export const Active: Story = {
  args: {
    status: 'active',
    children: 'Server Status',
  },
}

export const Inactive: Story = {
  args: {
    status: 'inactive',
    children: 'Server Status',
  },
}

Reference Documentation

Quick Reference Search

When searching reference files for specific patterns, use these grep commands:

bash

# Find composition patterns by type
grep -i "pattern.*:" references/composition.md

# Find specific composition examples
grep -i "iconbutton\|confirmbutton\|taginput" references/composition.md

# Find CSS variables by component
grep -i "\-\-btn\|--alert\|--card" references/css-variables.md

# Find CSS variable naming rules
grep -i "naming\|convention\|pattern" references/css-variables.md

# Find ARIA patterns and attributes
grep -i "aria-\|role=" references/accessibility.md

# Find WCAG requirements
grep -i "wcag\|contrast\|level aa" references/accessibility.md

# Find testing patterns
grep -i "describe\|test\|expect\|render" references/testing.md

# Find Storybook configuration
grep -i "meta\|story\|args" references/storybook.md

# Find architecture patterns
grep -i "polymorphic\|as prop\|compound" references/architecture.md