name	fpkit-developer
description	Guide for building applications with @fpkit/acss components. This skill should be used when composing custom React components from fpkit primitives, validating CSS variable naming conventions, extending fpkit components with custom behavior, or ensuring accessibility compliance in fpkit-based applications. Use when the user needs help with component composition patterns, CSS customization, or accessibility testing. Not for developing the @fpkit/acss library itself.
version	0.1.5

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