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:

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:

// 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:

// 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):

// 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):

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:

// 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:

# 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