# @fpkit/acss Documentation
Welcome to the @fpkit/acss documentation! This collection of guides helps you build accessible, maintainable applications using the fpkit component library.
---
## 📚 Guides
### [Theming Guide](./guides/theming.md)
Ship light/dark theming without a flash of the wrong theme on first paint.
**Topics:**
- `ThemeProvider`, `useTheme`, `ThemeToggle`
- How the `data-theme` attribute powers runtime switching
- `getThemeFoucScript()` for SSR (Astro, Next.js, Remix)
- Creating a custom theme
- Accessibility notes (`prefers-color-scheme`, toggle labeling)
**Use when:**
- Adding light/dark mode to an app
- Preventing theme flash in SSR frameworks
- Building a custom theme on top of fpkit
---
### [Design Tokens Guide](./guides/design-tokens.md)
Consume `@fpkit/acss/tokens` — the DTCG-compliant design token artifact that powers the Figma bridge and the public docs site.
**Topics:**
- Shipped categories: color, motion, breakpoints (typography and spacing are on the roadmap)
- The JSON artifact vs. the typed TS module (`var()` references)
- Feeding Figma bridges, docs sites, and custom CSS generators
- The extract-tokens + Style Dictionary pipeline
- Relationship to CSS variables
**Use when:**
- Building a docs site or design-system tool that reads fpkit tokens
- Bridging fpkit values into Figma variables
- Generating custom CSS output from the same source
---
### [CSS Variables Guide](./guides/css-variables.md)
Learn how to discover, customize, and override CSS custom properties in fpkit components.
**Topics:**
- Understanding the naming convention
- Discovering available variables
- Customization strategies (global, theme, component-specific)
- rem units and accessibility
- Framework integration (React, Next.js, CSS Modules)
**Use when:**
- Customizing component appearance
- Creating themes
- Building design systems
- Understanding fpkit styling architecture
---
### [Composition Guide](./guides/composition.md)
Master component composition patterns to build custom components by combining fpkit primitives.
**Topics:**
- Composition vs creation decision tree
- Common composition patterns (container + content, conditional, enhanced wrapper, compound)
- Real-world examples (AlertDialog, IconButton, TagInput)
- Anti-patterns to avoid
- TypeScript support for compositions
**Use when:**
- Building custom components
- Extending fpkit functionality
- Creating application-specific components
- Deciding whether to compose or create from scratch
---
### [Accessibility Guide](./guides/accessibility.md)
Understand and maintain WCAG 2.1 Level AA compliance when using and composing fpkit components.
**Topics:**
- Core accessibility principles
- ARIA attributes and patterns
- Keyboard navigation
- Focus management
- Screen reader support
- Color contrast requirements
- Testing accessibility (manual and automated)
**Use when:**
- Ensuring accessible applications
- Testing for WCAG compliance
- Implementing keyboard navigation
- Adding ARIA attributes
- Composing accessible custom components
---
### [Architecture Guide](./guides/architecture.md)
Learn fpkit's architectural patterns, component structure, and how to work effectively with the library.
**Topics:**
- Polymorphic UI component foundation
- Simple vs compound component patterns
- TypeScript support and prop types
- Composition patterns
- Styling architecture (data attributes, CSS variables)
- Props patterns and conventions
- Framework integration
**Use when:**
- Understanding fpkit component structure
- Working with polymorphic `as` prop
- Extending component props
- Integrating with frameworks (React, Next.js)
- Building type-safe compositions
---
### [Testing Guide](./guides/testing.md)
Test applications and custom components built with fpkit using Vitest and React Testing Library.
**Topics:**
- Vitest and React Testing Library setup
- Testing composed components
- Query best practices (getByRole, getByLabelText)
- Event testing (clicks, keyboard, forms)
- Accessibility testing (automated with jest-axe)
- Async testing and loading states
- Mock functions and test organization
**Use when:**
- Setting up test infrastructure
- Testing custom compositions
- Testing user interactions
- Testing accessibility
- Writing integration tests
---
### [Storybook Guide](./guides/storybook.md)
Document custom components and compositions using Storybook for development and showcase.
**Topics:**
- Storybook setup and configuration
- Story structure and patterns
- Documenting composed components
- CSS variable customization stories
- Interactive testing with play functions
- ArgTypes configuration
- Accessibility testing in Storybook
**Use when:**
- Documenting custom components
- Creating component showcases
- Interactive component development
- Testing components in isolation
- Building internal component libraries
---
### [Component Lifecycle Guide](./guides/component-lifecycle.md)
Understand the lifecycle tags (`experimental`, `beta`, `rc`, `stable`, `deprecated`) and the promotion criteria between them.
**Topics:**
- Lifecycle stage definitions and what they promise users
- How tags are applied in Storybook story meta objects
- Coverage signals that feed the [Component Maturity Dashboard](../../../apps/astro-builds/src/pages/status.astro): `hasTests`, `a11y-verified`, `dark-mode-verified`
- Promotion checklist for moving a component stage up (or demoting it)
**Use when:**
- Authoring a new component and choosing its initial lifecycle stage
- Reviewing whether a component is ready to promote from beta → rc → stable
- Reading the `/status` dashboard and interpreting its signals
---
## 🚀 Quick Start
### Installation
```bash
npm install @fpkit/acss
```
### Basic Usage
```tsx
import { Button, Card } from '@fpkit/acss'
import '@fpkit/acss/libs/index.css'
function App() {
return (
Welcome