@fpkit/acss

A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive styles. Built with TypeScript and designed for optimal tree-shaking and bundle size optimization.


📚 Storybook Documentation | 🎯 Component Playground

✨ Features

- 🎯 Dual Export Strategy: Choose between convenience (barrel exports) or optimization (individual imports)
- 📦 Tree-Shakable: Import only the components you need
- ♿ Accessible: Built with accessibility best practices
- 🎨 CSS Custom Properties: Reactive styling with CSS variables
- 📱 Responsive: Mobile-first design approach
- ⚡ TypeScript: Full type safety and excellent DX
- 🔧 Headless: Minimal styling, maximum customization

♿ Accessibility

FPKit is built with accessibility as a core principle, following WCAG 2.1 AA standards. All components support ARIA attributes and provide guidance for creating accessible applications.

$3

- Semantic HTML - Components use appropriate semantic elements by default
- ARIA Support - Full support for ARIA attributes on all components
- Keyboard Navigation - All interactive elements are keyboard accessible
- Screen Reader Friendly - Proper labeling and announcements for assistive technologies
- Focus Management - Visible focus indicators and programmatic focus control

$3

We recommend the following tools for testing accessibility in your applications:

#### Automated Testing

``bash


Install recommended packages

`js
// .eslintrc.js
{
"extends": ["plugin:jsx-a11y/recommended"],
"plugins": ["jsx-a11y"]
}
`

jest-axe - Automated accessibility testing in unit tests:

`tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
import { Button } from '@fpkit/acss/button';

expect.extend(toHaveNoViolations);

test('Button should have no accessibility violations', async () => {
const { container } = render(

Submit

);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
`

#### Manual Testing Checklist

When building components with FPKit, verify:

- [ ] Keyboard Navigation - All interactive elements are reachable and operable via keyboard
- [ ] Screen Reader - Test with VoiceOver (macOS), NVDA (Windows), or JAWS
- [ ] Focus Indicators - Visible focus states meet 3:1 contrast ratio (WCAG 2.4.7)
- [ ] Accessible Names - All interactive elements have accessible names (via text, aria-label, or aria-labelledby)
- [ ] Color Contrast - Text meets 4.5:1 contrast ratio for normal text, 3:1 for large text
- [ ] Semantic Structure - Proper heading hierarchy and landmark regions

$3

The foundational UI component demonstrates best practices:

`tsx
import { UI } from '@fpkit/acss';

// ✅ Good: Accessible button with aria-label




// ✅ Good: Semantic link with descriptive text

View all products


// ❌ Bad: Button without accessible name



`

See the UI component Storybook stories for more examples and anti-patterns to avoid.

📦 Installation

`bash
npm install @fpkit/acss


or

`tsx
import { Button, Card, Input, Modal } from '@fpkit/acss';
import '@fpkit/acss/styles';

function App() {
return (


`tsx
import { Button } from '@fpkit/acss/button';
import { Card } from '@fpkit/acss/card';
import { Input } from '@fpkit/acss/input';
import '@fpkit/acss/styles';

function App() {
return (


`tsx
// Barrel import
import { Button } from '@fpkit/acss';

// Individual import
import { Button } from '@fpkit/acss/button';

// Usage
console.log('clicked')}>
Click me


// With TypeScript
import { Button, type ButtonProps } from '@fpkit/acss/button';

const buttonProps: ButtonProps = {
type: 'submit',
disabled: false,
children: 'Submit Form'
};
`

$3

Flexible card component with composable parts:

`tsx
// Individual import
import { Card } from '@fpkit/acss/card';

// Usage

Card Title



This is the card content area.

// Custom styling

Styled Card
Content with custom styling

`

$3

Accessible modal dialog with focus management:

`tsx
import { Modal } from '@fpkit/acss/modal';

openChild="Open Modal"
closeChild="Close"
modalHeader={

Modal Title

`tsx
import { Input } from '@fpkit/acss/input';

type="email"
placeholder="Enter your email"
required
aria-label="Email address"
/>

// With field wrapper
import { Field } from '@fpkit/acss';


Email Address

Please enter a valid email

`

$3

Semantic navigation components:

`tsx
import { Nav, NavList, NavItem } from '@fpkit/acss';

`tsx
import { Text, Heading } from '@fpkit/acss';


Page Title



This is a paragraph with large text.



Muted text for secondary information.

`

🎨 Styling & Theming

FPKit uses CSS custom properties for theming and styling:

`css
/ Global theme variables /
:root {
--fp-color-primary: #007bff;
--fp-color-secondary: #6c757d;
--fp-spacing-sm: 0.5rem;
--fp-spacing-md: 1rem;
--fp-spacing-lg: 1.5rem;
--fp-border-radius: 0.375rem;
}

/ Component-specific styling /
.custom-button {
--fp-button-bg: var(--fp-color-primary);
--fp-button-color: white;
--fp-button-padding: var(--fp-spacing-md);
}
`

$3

`tsx
// Inline styles

Styled Button


// CSS classes

Styled card


// Data attributes for CSS targeting

Data Attribute Styling

`

🛠️ Framework Integration

$3

`tsx
// pages/_app.tsx
import '@fpkit/acss/styles';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
return ;
}

// pages/index.tsx
import { Button } from '@fpkit/acss/button';
import { Card } from '@fpkit/acss/card';

export default function Home() {
return (


`tsx
// main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import '@fpkit/acss/styles';
import App from './App.tsx';

ReactDOM.createRoot(document.getElementById('root')!).render(


,
);

// App.tsx
import { Button, Card } from '@fpkit/acss';

function App() {
return (

Vite + React + FPKit

Hello World


);
}

export default App;
`

📋 Available Components

$3

- Button - Accessible button with variants
- Card - Flexible card container with composable parts
- Modal - Accessible modal dialog
- Dialog - General purpose dialog component
- Input - Form input with validation
- Field - Form field wrapper with label and error
- Link - Accessible link component
- List - Semantic list components

$3

- Box - Generic container component
- Nav - Navigation components
- Landmarks - Semantic landmark components

$3

- Text - Semantic text component
- Heading - Heading component with sizes

$3

- Icon - SVG icon component
- Image - Responsive image component

$3

- Table - Accessible table components
- Tag - Tag/badge component
- Badge - Status badge component

$3

- TextToSpeech - Text-to-speech component
- Popover - Popover/tooltip component
- Breadcrumb - Navigation breadcrumbs

🎯 Import Strategies

$3

- Rapid prototyping
- Small applications
- When using many components
- Development/testing environments

$3

- Production applications
- Performance-critical apps
- When using few components
- Library/package development

$3

`bash


Barrel import (all components)

`tsx
import { Button, type ButtonProps } from '@fpkit/acss/button';
import { Card, type CardProps } from '@fpkit/acss/card';

// Type-safe props
const buttonProps: ButtonProps = {
type: 'button',
onClick: (e) => console.log(e),
children: 'Click me'
};

// Component with proper typing
const MyButton: React.FC = (props) => {
return ;
};
`

🧪 Testing

Components are designed for easy testing:

`tsx
import { render, screen } from '@testing-library/react';
import { Button } from '@fpkit/acss/button';

test('renders button with text', () => {
render(

Click me);
expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
});
`

📚 Documentation

Comprehensive guides to help you build accessible, maintainable applications with @fpkit/acss:

$3

- CSS Variables Guide - Learn how to discover and customize CSS custom properties for theming and styling
- Composition Guide - Master component composition patterns to build custom components by combining fpkit primitives
- Accessibility Guide - Understand and maintain WCAG 2.1 Level AA compliance when using and composing components
- Architecture Guide - Learn fpkit's architectural patterns, component structure, and how to work effectively with the library
- Testing Guide - Test applications and custom components using Vitest and React Testing Library
- Storybook Guide - Document custom components and compositions using Storybook

$3

- Documentation Index - Complete documentation hub with guide navigator and workflows
- Storybook - Interactive component documentation and playground

$3

Customizing component appearance?
→ Start with CSS Variables Guide

Building a custom component?
→ Read Composition Guide, then Architecture Guide

Ensuring accessibility?
→ Study Accessibility Guide

Testing components?
→ Follow Testing Guide

🤖 Claude Code Skill

Supercharge your development workflow with the fpkit-developer skill for Claude Code! This AI assistant skill helps you build applications using @fpkit/acss components with best practices baked in.

$3

- ✅ Component Composition - Get guidance on composing custom components from fpkit primitives
- ✅ CSS Variable Validation - Automatically validate your custom styles against fpkit naming conventions
- ✅ Accessibility Assistance - Maintain WCAG 2.1 Level AA compliance with automated checks
- ✅ TypeScript Support - Type-safe component compositions with proper prop inheritance
- ✅ Testing Guidance - Best practices for testing fpkit-based components

$3

$3

`bash
npx gitpick shawn-sandy/acss/tree/main/.claude/skills/fpkit-developer ~/.claude/skills/fpkit-developer
`

$3

`bash
cd /path/to/your/project
`

`bash
npx gitpick shawn-sandy/acss/tree/main/.claude/skills/fpkit-developer ./.claude/skills/fpkit-developer
`

What is gitpick? A lightweight tool (<35kb) for selective cloning from GitHub repositories. Learn more at github.com/nrjdalal/gitpick.

$3

Once installed, the skill activates automatically when working with @fpkit/acss:

Compose a Custom Component:
`
You: "Create a StatusButton that combines Button and Badge from fpkit"
Claude: [Provides composition with proper TypeScript types and accessibility]
`

Validate Your Styles:
`
You: "Check if my CSS variables follow fpkit conventions"
Claude: [Validates naming patterns, units, and provides fixes]
`

Ensure Accessibility:
`
You: "Review this component for WCAG AA compliance"
Claude: [Analyzes semantic HTML, ARIA, keyboard nav, and color contrast]
``

$3

- Full Skill Documentation - Complete usage guide and examples
- Reference Guides - Composition patterns, CSS variables, accessibility, and more
- Requirements: Claude Code, @fpkit/acss installed in your project

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License

Copyright (c) 2024 Shawn Sandy

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.