import { Meta } from "@storybook/addon-docs/blocks";

<Meta title="Introduction" />

# @fpkit/acss Documentation

Welcome to the **@fpkit/acss** component library documentation! These guides
help you build accessible, maintainable applications using fpkit components.

---

## 📚 Available Guides

### [CSS Variables Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/css-variables.md)

Learn how to discover and customize CSS custom properties for theming and
styling.

**Topics covered:**

- Understanding the naming convention (`--component-property`)
- Discovering available variables (DevTools, autocomplete)
- Customization strategies (global, theme, component-specific)
- rem units and accessibility
- Framework integration (React, Next.js, CSS Modules)

**Use when:** Customizing component appearance, creating themes, or building
design systems.

---

### [Composition Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/composition.md)

Master component composition patterns to build custom components by combining
fpkit primitives.

**Topics covered:**

- Composition vs creation decision tree
- Common composition patterns (container + content, conditional, enhanced
  wrapper)
- Real-world examples (AlertDialog, IconButton, TagInput, ConfirmButton)
- Anti-patterns to avoid
- TypeScript support for compositions

**Use when:** Building custom components, extending fpkit functionality, or
creating application-specific components.

---

### [Accessibility Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/accessibility.md)

Understand and maintain WCAG 2.1 Level AA compliance when using and composing
fpkit components.

**Topics covered:**

- Core accessibility principles
- ARIA attributes and patterns
- Keyboard navigation
- Focus management
- Screen reader support
- Color contrast requirements
- Testing accessibility (manual and automated with jest-axe)

**Use when:** Ensuring accessible applications, testing for WCAG compliance,
implementing keyboard navigation, or composing accessible custom components.

---

### [Architecture Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/architecture.md)

Learn fpkit's architectural patterns, component structure, and how to work
effectively with the library.

**Topics covered:**

- 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, or integrating with frameworks.

---

### [Testing Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/testing.md)

Test applications and custom components built with fpkit using Vitest and React
Testing Library.

**Topics covered:**

- 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, or testing accessibility.

---

### [Storybook Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/storybook.md)

Document custom components and compositions using Storybook for development and
showcase.

**Topics covered:**

- Storybook setup and configuration
- Story structure and patterns
- Documenting composed components
- CSS variable customization stories
- Interactive testing with play functions
- ArgTypes configuration
- Complete examples

**Use when:** Documenting custom components, creating component showcases,
interactive component development, or building internal component libraries.

---

## 🎯 Quick Start by Task

### I want to customize component appearance

1. Read
   [CSS Variables Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/css-variables.md)
2. Use browser DevTools to discover variables
3. Override in your CSS with `:root` or scoped selectors

**Example:**

```css
:root {
  --btn-primary-bg: #0066cc;
  --btn-padding-inline: 2rem;
  --btn-radius: 0.5rem;
}
```

---

### I want to build a custom component

1. Check
   [Composition Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/composition.md)
   decision tree
2. Review
   [Architecture Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/architecture.md)
   patterns
3. Compose from fpkit primitives
4. Maintain accessibility with
   [Accessibility Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/accessibility.md)

**Example:**

```tsx
import { Button, Badge } from "@fpkit/acss";

export const StatusButton = ({ status, children, ...props }) => (
  <Button {...props}>
    {children}
    <Badge variant={status}>{status}</Badge>
  </Button>
);
```

---

### I want to ensure my app is accessible

1. Study
   [Accessibility Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/accessibility.md)
2. Test with keyboard navigation
3. Use automated testing with jest-axe
   ([Testing Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/testing.md))
4. Verify color contrast ratios

**Example:**

```tsx
import { axe, toHaveNoViolations } from "jest-axe";

expect.extend(toHaveNoViolations);

it("should not have accessibility violations", async () => {
  const { container } = render(
    <StatusButton status="active">Server</StatusButton>
  );
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});
```

---

### I want to test my components

1. Setup from
   [Testing Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/testing.md)
2. Focus tests on your custom logic (fpkit is already tested)
3. Use `getByRole` queries for accessibility
4. Test user interactions and keyboard navigation

**Example:**

```tsx
import { render, screen } from "@testing-library/react";
import { userEvent } from "@testing-library/user-event";

it("calls onClick when clicked", async () => {
  const handleClick = vi.fn();
  render(<StatusButton onClick={handleClick}>Click me</StatusButton>);

  await userEvent.click(screen.getByRole("button"));
  expect(handleClick).toHaveBeenCalledOnce();
});
```

---

## 💡 Key Concepts

### Composition Over Creation

fpkit encourages **composing** existing components rather than creating new ones
from scratch:

```tsx
// ✅ Good - compose from fpkit components
import { Button, Badge } from "@fpkit/acss";

const StatusButton = ({ status, children }) => (
  <Button>
    {children}
    <Badge>{status}</Badge>
  </Button>
);

// ❌ Less ideal - creating from scratch
const StatusButton = ({ status, children }) => (
  <button className="status-button">
    {children}
    <span className="badge">{status}</span>
  </button>
);
```

**Benefits:** Consistency, maintained accessibility, reduced code, leveraged
test coverage.

---

### CSS Variables for Customization

All fpkit components use **CSS custom properties** for styling:

```css
/* Global customization */
:root {
  --btn-primary-bg: #0066cc;
  --btn-padding-inline: 2rem;
}

/* Component-specific */
.hero-button {
  --btn-padding-inline: 3rem;
  --btn-fs: 1.25rem;
}
```

**Benefits:** Theme creation, component-specific customization, real-time
updates, scoped styling.

---

### WCAG 2.1 Level AA Compliance

fpkit components meet **WCAG 2.1 Level AA** standards by default:

- Semantic HTML elements
- Proper ARIA attributes
- Keyboard navigation
- Screen reader support
- Sufficient color contrast

**Your responsibility:** Maintain accessibility when composing and customizing
components.

---

### Polymorphic Components

Most fpkit components support the **`as` prop** for rendering as different HTML
elements:

```tsx
// Button as link
<Button as="a" href="/page">Navigate</Button>

// Card as section
<Card as="section">Content</Card>
```

**Benefits:** Semantic flexibility, type-safe props, maintained component
behavior.

---

## 🔗 External Resources

### fpkit Resources

- [GitHub Repository](https://github.com/shawn-sandy/acss)
- [npm Package](https://www.npmjs.com/package/@fpkit/acss)

### Web Standards

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [MDN Web Docs](https://developer.mozilla.org/)

### Testing Resources

- [Vitest Documentation](https://vitest.dev/)
- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
- [jest-axe](https://github.com/nickcolley/jest-axe)

---

## 📖 Full Documentation

For the complete, offline-accessible documentation, see the `docs/` directory in
the npm package or
[view on GitHub](https://github.com/shawn-sandy/acss/tree/main/packages/fpkit/docs).

Each guide is available as a detailed markdown file with:

- Comprehensive explanations
- Code examples
- Best practices
- Troubleshooting tips
- Additional resources

---

**Happy building with @fpkit/acss!** 🚀