### Get Guides

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/mcp/page.mdx

Get setup, configuration, and integration guides for the Axiom Design System.

```APIDOC
## get_guides

### Description
Get setup, configuration, and integration guides for the Axiom Design System (including this one).

### Parameters
#### Query Parameters
- **names** (string, optional) - Space-separated guide names to fetch (e.g., "css-imports css-layers"). Omit to list all available guides.
```

--------------------------------

### get_guides

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Retrieves setup, configuration, and integration guides for the Axiom Design System. If no names are provided, it lists all available guides. If names are provided, it returns the markdown content for the requested guides along with a list of all available guide names for self-correction.

```APIDOC
## get_guides

### Description
Get setup, configuration, and integration guides for the Axiom Design System.

### Parameters
#### Query Parameters
- **names** (string, optional): Space-separated guide names to fetch (e.g., `"css-imports css-layers"`). Omit to list all available guides (names + titles).

### Returns
When `names` is omitted, the list of available guides (name + title). When `names` is provided, the markdown content for each requested guide, plus the full list of available guide names so an invalid name self-corrects.

### Example Usage
```javascript
// To get a list of all available guides:
get_guides()

// To get specific guides:
get_guides({ names: "css-imports css-layers" })
```
```

--------------------------------

### Pill Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/pill/page.mdx

Demonstrates the basic usage of the Pill component. No specific setup is required beyond importing the component.

```javascript
import { Pill } from "@/components";

function App() {
  return <Pill label="Pill Label" />;
}
```

--------------------------------

### Badge Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/badge/page.mdx

Demonstrates the basic usage of the Badge component. No specific setup is required beyond importing the component.

```javascript
import { Badge } from "@/components";

function App() {
  return <Badge>99</Badge>;
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/CONTRIBUTING.md

Install all project dependencies using pnpm.

```sh
pnpm install
```

--------------------------------

### Install @optiaxiom/globals

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/globals/README.md

Install the package using npm.

```sh
npm install @optiaxiom/globals
```

--------------------------------

### Get Patterns

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/mcp/page.mdx

Find usage examples showing how Axiom components work together. Allows searching within example titles and limiting the number of results.

```APIDOC
## get_patterns

### Description
Find usage examples showing how Axiom components work together. Returns real working examples from the docs.

### Parameters
#### Query Parameters
- **components** (string, required) - Space-separated component names to find patterns for (e.g., "Field Input Button"). Returns examples that use these components together.
- **query** (string, optional) - Search within example titles to find specific patterns (e.g., "addon", "form", "disabled").
- **limit** (number, optional) - Maximum number of examples to return (default: 5, max: 10)
```

--------------------------------

### Start Development Environment

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/CONTRIBUTING.md

Start the development environment for all apps and packages, or specific ones like docs or Storybook.

```sh
pnpm dev

# Or start specific apps
pnpm dev:docs      # Documentation site only
pnpm dev:storybook # Storybook only
```

--------------------------------

### Start Storybook Development Server

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/storybook/README.md

Run this command to start a Storybook instance on port 6006 for development.

```sh
pnpm -F storybook... --parallel dev
```

--------------------------------

### Install @optiaxiom/icons package

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/icons/page.mdx

Install the @optiaxiom/icons package using npm or yarn.

```sh
npm install @optiaxiom/icons
```

--------------------------------

### Basic Axiom Button Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/react/README.md

A simple example demonstrating how to use the Axiom Button component.

```jsx
import { Button } from "@optiaxiom/react";

<Button>Click me</Button>;
```

--------------------------------

### Install @optiaxiom/react Package

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/page.mdx

Use npm or yarn to install the core OptiAxiom React package.

```sh
npm install @optiaxiom/react
```

--------------------------------

### Project Installation with npm

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Install the MCP server as a development dependency in your project using npm.

```bash
npm install --save-dev @optiaxiom/mcp
```

--------------------------------

### Project Installation with pnpm

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Install the MCP server as a development dependency in your project using pnpm.

```bash
pnpm add -D @optiaxiom/mcp
```

--------------------------------

### Install Axiom Web Components with npm

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/web-components/README.md

Use npm to install the web components package. This is the first step for bundler usage.

```sh
npm install @optiaxiom/web-components
```

--------------------------------

### Install Node.js with FNM

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/README.md

Install the required Node.js version using FNM (Fast Node Manager). Ensure FNM is installed first.

```sh
fnm install
```

--------------------------------

### Get Component

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/mcp/page.mdx

Get information about a specific component, including its description, import statement, sub-components, and example titles. Optionally search for specific props.

```APIDOC
## get_component

### Description
Get information about a specific component. Returns the component's description, import statement, sub-components, and example titles by default. Use the optional `props` parameter to search for specific props.

### Parameters
#### Query Parameters
- **name** (string, required) - Component name (e.g., "Button", "Dialog", "Alert")
- **props** (string, optional) - Search query to find specific props by name or description (e.g., "appearance size", "loading", "padding background"). Searches both component-specific props and style props. Omit to get just the component overview without any prop definitions.
```

--------------------------------

### Start Development Environment

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/README.md

Execute this command to launch the entire development environment, including all apps and packages in dev mode.

```sh
pnpm dev
```

--------------------------------

### Configure MCP Server with Global Installation

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/mcp/page.mdx

Update your workspace configuration to use the globally installed MCP server. This JSON configuration assumes the global installation.

```json
{
  "servers": {
    "axiom": {
      "command": "axiom-mcp"
    }
  }
}
```

--------------------------------

### Button Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/button/page.mdx

Demonstrates the basic usage of the Button component.

```javascript
import { Button } from "@/components";

function MyComponent() {
  return <Button>Click me</Button>;
}
```

--------------------------------

### Global Installation with pnpm

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Install the MCP server globally using pnpm. This command is used for system-wide access.

```bash
pnpm add -g @optiaxiom/mcp
```

--------------------------------

### get_patterns

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Finds usage examples demonstrating how Axiom components can be composed together. Allows searching within example titles for specific patterns.

```APIDOC
## get_patterns

### Description
Find usage examples showing how Axiom components work together. Returns real working examples from the docs that demonstrate component composition patterns.

### Parameters
#### Path Parameters
- `components` (string, required): Space-separated component names to find patterns for (e.g., "Field Input Button"). Returns examples that use these components together.
- `query` (string, optional): Search within example titles to find specific patterns (e.g., "addon", "form", "disabled").
- `limit` (number, optional): Maximum number of examples to return (default: 5, max: 10)

### Returns
Array of matching examples with code (filename → file contents) and title.
```

--------------------------------

### Responsive Flex Direction Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/flex-direction/page.mdx

Illustrates how to apply responsive design principles to the `flexDirection` prop, allowing layout adjustments based on screen size. This example utilizes the `resizable` prop for interactive testing.

```javascript
import { Demo } from "@/components";

<Demo component="flex-direction/responsive-usage" resizable />
```

--------------------------------

### Install @optimizely/axiom-fonts package

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/fonts/page.mdx

Install the private @optimizely/axiom-fonts package using npm or yarn. Ensure you have access to the private package repository.

```sh
npm install @optimizely/axiom-fonts
```

--------------------------------

### Install Axiom MCP Server for AI Assistants

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/README.md

Install the MCP server globally to enable AI assistants like Claude Code and Cursor to access Axiom component metadata. This requires Node.js and npm.

```sh
npm install -g @optiaxiom/mcp
```

--------------------------------

### Responsive Flex Wrap Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/flex-wrap/page.mdx

Illustrates how to implement responsive flex wrapping behavior, allowing adjustments based on screen size or container dimensions.

```javascript
import { Demo } from "@/components";

<Demo component="flex-wrap/responsive-usage" resizable scrollable />
```

--------------------------------

### Run Docs Development Server

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/README.md

Execute this command to start only the documentation development server. It will spin up a Next.js instance on port 5055.

```sh
pnpm -F docs... --parallel dev
```

--------------------------------

### Responsive Flexbox Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/flex/page.mdx

Illustrates how to apply flexbox properties responsively. This is useful for creating layouts that adapt to different screen sizes.

```javascript
<Demo component="flex/flex-responsive-usage" resizable />
```

--------------------------------

### Field Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/field/page.mdx

Wrap your input controls with the Field component to display additional context for the input. This is the basic setup for using the Field component.

```jsx
import { Field, Input } from "@optimizely/optimizely-ui";

<Field label="Name" name="name">
  <Input />
</Field>
```

--------------------------------

### Tooltip Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/tooltip/page.mdx

Basic usage of the Tooltip component. This example demonstrates how to integrate the tooltip into your application.

```javascript
import { Tooltip } from "@/components/ui/tooltip";

function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button variant="outline">Hover me</Button>
      </TooltipTrigger>
      <TooltipContent>
        <p>Add kpis, goals, objectives, and more</p>
      </TooltipContent>
    </Tooltip>
  );
}

export default TooltipDemo;
```

--------------------------------

### DateRangePicker Migration Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-range-picker/page.mdx

Illustrates the change in import path for the DateRangePicker component from an unstable version to the stable one.

```jsx
// Before
import { DateRangePicker } from "@optiaxiom/react/unstable";

// After
import { DateRangePicker } from "@optiaxiom/react";
```

--------------------------------

### Flex Wrap Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/flex-wrap/page.mdx

Demonstrates the basic usage of the `flexWrap` prop to control how flex items wrap within a container.

```javascript
import { Demo } from "@/components";

<Demo component="flex-wrap/usage" scrollable />
```

--------------------------------

### Virtualized Menu Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/menu/page.mdx

The Menu component automatically employs virtualization for efficient rendering of a large number of items.

```jsx
import { Menu, MenuTrigger, MenuContent, MenuItem } from "@optiaxiom/react";

const largeList = Array.from({ length: 1000 }, (_, i) => ({ label: `Item ${i + 1}`, value: `${i + 1}` }));

export const VirtualizedMenu = () => (
  <Menu>
    <MenuTrigger />
    <MenuContent>
      {largeList.map((item) => (
        <MenuItem key={item.value}>{item.label}</MenuItem>
      ))}
    </MenuContent>
  </Menu>
);
```

--------------------------------

### Flexbox Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/flex/page.mdx

Demonstrates various flex item behaviors including initial, none, auto, and 1. Use this to understand how flex items grow and shrink based on their content and available space.

```javascript
import { Demo, Scale } from "@/components";

<Scale values="flex" />

<Demo component="flex/flex-usage" resizable />
```

--------------------------------

### Kbd Component Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/kbd/page.mdx

Demonstrates the basic usage of the Kbd component for inline keyboard input representation. No specific setup is required beyond importing the component.

```javascript
import { Kbd } from "@/components";

<Kbd>Shift</Kbd>
```

--------------------------------

### Build MCP Package

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Use this command to build the MCP package during development. Ensure you have pnpm installed and are in the project root.

```bash
pnpm -F mcp... build
```

--------------------------------

### DateInput Component Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-input/page.mdx

Basic usage of the DateInput component. This example demonstrates how to render the component.

```jsx
import { DateInput } from "@optiaxiom/react";

<DateInput />
```

--------------------------------

### Get Tests

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/mcp/page.mdx

Get vetted reference test files showing the repo's testing conventions. Use when writing or fixing a spec for an Axiom component.

```APIDOC
## get_tests

### Description
Get vetted reference test files showing the repo's testing conventions (custom `vitest.rtl` render helper, role/name queries, accessibility assertions). Use when writing or fixing a spec for an Axiom component.

### Parameters
#### Query Parameters
- **components** (string, optional) - Space-separated component names to find reference tests for (e.g., "Alert Button"). Omit to list all available reference tests.
- **limit** (number, optional) - Maximum number of reference tests to return when searching by component (default: 5). Ignored when listing all tests.
```

--------------------------------

### Checkbox with Description

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/checkbox/page.mdx

Example of adding helper text to the Checkbox using the `description` prop.

```javascript
import { Checkbox } from "@/components";

function App() {
  return (
    <Checkbox
      label="Email updates"
      description="Receive weekly updates via email."
    />
  );
}
```

--------------------------------

### Flex to Group Migration with Props (Before)

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/codemod/README.md

Example of a Flex component with existing props, demonstrating how it appears before the flex-to-group codemod.

```tsx
<Flex flexDirection="row" gap="8">
  <Button>Cancel</Button>
  <Button>Save</Button>
</Flex>
```

--------------------------------

### Menu Creatable Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/menu/page.mdx

Allows users to add new entries to the menu on the fly by customizing filter behavior.

```tsx
import { Menu, MenuContent, MenuTrigger, MenuOption } from "@optiaxiom/react";

export default () => (
  <Menu
    options={[
      { label: "Item 1" },
      { label: "Item 2", visible: false },
      { label: "Item 3", visible: false },
    ]}>
    <MenuTrigger />
    <MenuContent />
  </Menu>
);
```

--------------------------------

### Axiom Form with Validation Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/react/README.md

Demonstrates a login form using Axiom components like Field, Input, and Button. Includes basic layout for email and password fields.

```jsx
import { Button, Field, Group, Input } from "@optiaxiom/react";

function LoginForm() {
  return (
    <Group alignItems="start" flexDirection="column" gap="16">
      <Field label="Email">
        <Input placeholder="you@example.com" type="email" />
      </Field>
      <Field label="Password">
        <Input type="password" />
      </Field>
      <Button appearance="primary">Sign In</Button>
    </Group>
  );
}
```

--------------------------------

### Switch Demo with Dynamic Size Prop

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/README.md

Optionally specify props on the `App` component to expose dynamic demo controls. This example allows controlling the `size` prop of the Switch.

```tsx
// demos/switch/size-usage/App.tsx
import type { ComponentPropsWithRef } from "react";

import { Switch } from "@optiaxiom/react";

export function App({ size }: Pick<ComponentPropsWithRef<typeof Switch>, "size">) {
  return <Switch size={size}>Label</Switch>;
}
```

--------------------------------

### DateInput Placeholder Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-input/page.mdx

Demonstrates using the `placeholder` prop with a `DateInput`. The placeholder value must be a valid date or time object.

```jsx
import { DateInput } from "@optiaxiom/react";

<DateInput placeholder="2024-01-01" />
```

--------------------------------

### Flex to Group Migration Example (Before)

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/codemod/README.md

Illustrates the structure of a React component using the deprecated Flex component before codemod transformation.

```tsx
import { Flex } from "@optiaxiom/react";

function MyComponent() {
  return (
    <Flex>
      <div>1</div>
      <div>2</div>
    </Flex>
  );
}
```

--------------------------------

### Correct Page Structure Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/README.md

Documentation pages must follow a hierarchical structure with H2 sections immediately followed by an H3 subsection. This ensures proper styling and organization.

```mdx
✅ CORRECT:

## Installation

### Claude Code

Add the MCP server to your workspace configuration...

### Cursor

Add to your Cursor MCP configuration...
```

--------------------------------

### Tabs Anatomy Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/tabs/page.mdx

Demonstrates the basic structure of the Tabs component, including TabsList, TabsTrigger, and TabsContent.

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@optiaxiom/react";

export default () => (
  <Tabs>
    <TabsList>
      <TabsTrigger />
    </TabsList>

    <TabsContent />
  </Tabs>
);
```

--------------------------------

### Build Documentation

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/README.md

Run this command to build the documentation site.

```sh
pnpm -F docs... build
```

--------------------------------

### Tooltip Placement

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/tooltip/page.mdx

Control the placement of the tooltip using the `side` and `align` props. This example shows default placement.

```javascript
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";

function PlacementTooltipDemo() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <Button variant="outline">Hover</Button>
        </TooltipTrigger>
        <TooltipContent side="right" align="start" sideOffset={5}>
          <p>Add kpis, goals, objectives, and more</p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

export default PlacementTooltipDemo;
```

--------------------------------

### AuthProvider Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/auth-provider/page.mdx

Render AuthProvider near the root of your application to pass user credentials. Ensure you replace 'INSERT_INSTANCE_ID_HERE' and 'INSERT_AUTH_TOKEN_HERE' with your actual credentials.

```jsx
import { AuthProvider } from "@optiaxiom/react";

export function App() {
  return (
    <AuthProvider
      instance="INSERT_INSTANCE_ID_HERE"
      token="INSERT_AUTH_TOKEN_HERE"
    >
      {/* Your app code here */}
    </AuthProvider>
  );
}
```

--------------------------------

### Axiom Layout with Box and Group

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/react/README.md

Illustrates using Box and Group components for layout, styling, and content arrangement. This example shows a card-like structure with a heading and text.

```jsx
import { Box, Group, Heading, Text } from "@optiaxiom/react";

function Sample() {
  return (
    <Box bg="bg.default" color="fg.default" p="16" rounded="md" shadow="sm">
      <Group flexDirection="column" gap="16">
        <Heading level="3">Sample Title</Heading>
        <Text>Sample description goes here</Text>
      </Group>
    </Box>
  );
}
```

--------------------------------

### Box Shadow Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/box-shadow/page.mdx

Demonstrates the standard usage of the box shadow functionality. This component is typically used for elements that require a visible shadow.

```javascript
<Demo component="box-shadow/usage" />
```

--------------------------------

### Flex to Group Migration Example (After)

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/codemod/README.md

Shows the transformed React component after applying the flex-to-group codemod, using the Group component with appropriate props.

```tsx
import { Flex, Group } from "@optiaxiom/react";

function MyComponent() {
  return (
    <Group flexDirection="column" gap="16">
      <div>1</div>
      <div>2</div>
    </Group>
  );
}
```

--------------------------------

### Card Component Migration (v1.6.0)

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/card/page.mdx

Provides an example of how to update imports for the Card component after it was moved out of 'unstable' in version 1.6.0.

```jsx
// Before
import { Card } from "@optiaxiom/react/unstable";

// After
import { Card } from "@optiaxiom/react";
```

--------------------------------

### Run Codemod with npx

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/codemod/README.md

Use npx to run codemods directly without installation. Specify the transform and the target path.

```bash
npx @optiaxiom/codemod <transform> <path>
```

--------------------------------

### DateInput Date Matchers Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-input/page.mdx

Demonstrates using various matcher types (dates, ranges, intervals, day of week, custom functions) with the `holiday` and `weekend` props in DateInput.

```jsx
import { DateInput } from "@optiaxiom/react";

<DateInput
  holiday={[
    "2024-01-01",
    { start: "2024-04-10", end: "2024-04-12" },
    { after: "2024-12-20" },
    { weekday: [5] },
    ({ date }) => date.day === 15
  ]}
/>
```

--------------------------------

### Controlled DateInput Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-input/page.mdx

Demonstrates a controlled DateInput component using `value` and `onValueChange` props. This allows for external state management of the date input.

```jsx
import { useState } from "react";
import { DateInput } from "@optiaxiom/react";

function ControlledDateInput() {
  const [value, setValue] = useState("2024-01-01");

  return (
    <DateInput
      value={value}
      onValueChange={(e) => setValue(e.value)}
    />
  );
}
```

--------------------------------

### Flex Direction Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/flex-direction/page.mdx

Demonstrates the basic usage of the `flexDirection` prop to control the layout direction of flex items. This component is part of the Optimizely component library.

```javascript
import { Demo } from "@/components";

<Demo component="flex-direction/usage" />
```

--------------------------------

### Use Axiom Components in React

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/react/README.md

Import and use Axiom components like Box, Button, Group, and Input within your React application. This example demonstrates a basic layout with input and a primary button.

```jsx
import { Box, Button, Group, Input } from "@optiaxiom/react";

export function MyComponent() {
  return (
    <Group alignItems="start" flexDirection="column" gap="16">
      <Input placeholder="Enter text..." />
      <Button appearance="primary">Submit</Button>
    </Group>
  );
}
```

--------------------------------

### Get Tokens

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/mcp/page.mdx

Get design token mappings for converting hardcoded values to semantic tokens.

```APIDOC
## get_tokens

### Description
Get design token mappings for converting hardcoded values to semantic tokens (e.g., `#4F576E` → `fg.secondary`, `32px` height → `h="md"`).

### Parameters
#### Query Parameters
- **categories** (string[], optional) - Filter to specific token categories. Valid values: `borderRadius`, `boxShadow`, `colors`, `duration`, `fontFamily`, `fontSize`, `maxSize`, `size`, `zIndex`. Returns all categories if omitted.
```

--------------------------------

### Build the Project

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/CONTRIBUTING.md

Build all packages or a specific package using pnpm.

```sh
pnpm build          # Build all packages
pnpm -F react build # Build specific package
```

--------------------------------

### Install DataTable Peer Dependencies

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/data-table/page.mdx

Install the required peer dependencies for the DataTable component using npm or yarn.

```sh
npm install @tanstack/react-table
```

--------------------------------

### Install Webpack CSS Loaders

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/css-imports/page.mdx

Install `style-loader` and `css-loader` as development dependencies to handle CSS files in your Webpack configuration.

```bash
npm install -D style-loader css-loader
```

--------------------------------

### Sortable Card Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/sortable/page.mdx

Provides an example of integrating Sortable components with the Card component to create a sortable list of cards.

```tsx
<Demo component="sortable/card-usage" />
```

--------------------------------

### Build Storybook

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/storybook/README.md

Execute this command to build the static Storybook assets.

```sh
pnpm -F storybook... build
```

--------------------------------

### Basic CDN Usage with AxiomProvider

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/web-components/README.md

After importing via CDN, wrap your application with the ax-axiom-provider element. Components are then available under the ax-* prefix.

```html
<ax-axiom-provider>
  <ax-button>Hello World!</ax-button>
</ax-axiom-provider>
```

--------------------------------

### Clone the Repository

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/CONTRIBUTING.md

Clone the Optiaxiom repository and navigate into the project directory.

```sh
git clone https://github.com/your-username/optiaxiom.git
cd optiaxiom
```

--------------------------------

### Controlled Component Example with State

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/storybook/README.md

Provides an example of a controlled component (DateInput) within a story, managing its state using `useState` and demonstrating how to update and display the current value.

```tsx
export const Controlled: Story = {
  render: function Sample(args) {
    const [value, setValue] = useState("");

    return (
      <Group flexDirection="column" gap="16">
        <DateInput
          {...args}
          onChange={(event) => setValue(event.target.value)}
          value={value}
        />
        <Text fontSize="md">Current value: {value}</Text>
        <Button onClick={() => setValue("")}>Clear</Button>
      </Group>
    );
  },
};
```

--------------------------------

### Checkbox Form Integration

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/checkbox/page.mdx

Example of integrating Checkbox with react-hook-form for form management.

```javascript
import { Checkbox } from "@/components";
import { useForm } from "react-hook-form";

function App() {
  const { register } = useForm();

  return (
    <Checkbox
      label="Enable notifications"
      {...register("enableNotifications")}
    />
  );
}
```

--------------------------------

### Basic Usage with Bundler

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/web-components/README.md

Wrap your application with AxiomProvider and import components directly. Ensure AxiomProvider is used to enable component functionality.

```tsx
import { AxiomProvider, Button } from "@optiaxiom/web-components";

function App() {
  return (
    <AxiomProvider>
      <Button>Hello World!</Button>
    </AxiomProvider>
  );
}
```

--------------------------------

### Input Component Form Integration

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/input/page.mdx

Example of integrating the Input component with react-hook-form for validation and error handling.

```javascript
import { Input } from "@optiaxiom/react";
import { useForm } from "react-hook-form";

function App() {
  const { register, formState: { errors } } = useForm();

  return (
    <Input
      {...register("myInput")}
      placeholder="Enter text here"
      error={errors.myInput?.message}
    />
  );
}
```

--------------------------------

### Input Component Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/input/page.mdx

Demonstrates the basic usage of the Input component for capturing user input.

```javascript
import { Input } from "@optiaxiom/react";

function App() {
  return <Input placeholder="Enter text here" />;
}
```

--------------------------------

### Mock CSS Imports with Jest

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/test-environments/page.mdx

Configure Jest to stub CSS imports by installing `jest-transform-stub` and updating your `jest.config.js`.

```bash
npm install -D jest-transform-stub
```

--------------------------------

### Include Demo Component in MDX

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/README.md

Use the `Demo` component in MDX files to showcase component usages. Specify the component path relative to the `demos/` folder.

```mdx
{/* app/(docs)/components/switch/page.mdx */}
import { Demo } from "@/components";

<Demo component="switch/usage" />

<Demo component="switch/size-usage" />
```

--------------------------------

### Kbd Component with Key Codes

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/kbd/page.mdx

Shows how to use the `keys` prop to display commonly used key codes with the Kbd component. This is useful for illustrating keyboard shortcuts.

```javascript
import { Kbd } from "@/components";

<Kbd keys={["Ctrl", "C"]} />
```

--------------------------------

### Run Linting and Tests

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/CONTRIBUTING.md

Run type-checking, formatting, linting, and tests. Use `--no-fix` for CI checks.

```sh
pnpm lint           # Type-check (tsgo), format (oxfmt), and lint (oxlint)
pnpm lint --no-fix  # Same, but check-only (no auto-format/fix) — used in CI
pnpm test           # Run tests in watch mode
pnpm test run       # Run tests once
```

--------------------------------

### Disable Animations in Tests

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/test-environments/page.mdx

Set `TransitionGlobalConfig.skipAnimations` to `true` in your global test setup to prevent animations during unit tests.

```typescript
import { TransitionGlobalConfig } from "@optiaxiom/react";

// Do this in your global test setup file
TransitionGlobalConfig.skipAnimations = true;
```

--------------------------------

### Build Project or Individual Packages

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/README.md

Use the build command to compile the entire project or specific packages. The -F flag allows targeting individual packages.

```sh
pnpm build
```

```sh
# build react only
pnpm -F react build
```

--------------------------------

### Dismissible Pill Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/pill/page.mdx

Shows how to make a Pill dismissible by providing an `onDismiss` function. This adds a close button to the pill.

```javascript
import { Pill } from "@/components";

function App() {
  const handleDismiss = () => {
    console.log('Pill dismissed');
  };

  return <Pill label="Dismissible Pill" onDismiss={handleDismiss} />;
}
```

--------------------------------

### Input Component with Text Addons

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/input/page.mdx

Demonstrates adding text labels like currency symbols or prefixes before or after the input using `addonBefore` and `addonAfter` props.

```javascript
import { Input } from "@optiaxiom/react";

function App() {
  return (
    <>
      <Input addonBefore="$" placeholder="Amount" />
      <Input addonAfter="/hr" placeholder="Rate" />
    </>
  );
}
```

--------------------------------

### Input Component Appearance

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/input/page.mdx

Demonstrates selecting different input appearances using the `appearance` prop.

```javascript
import { Input } from "@optiaxiom/react";

function App() {
  return (
    <>
      <Input appearance="outline" placeholder="Outline" />
      <Input appearance="filled" placeholder="Filled" />
      <Input appearance="flushed" placeholder="Flushed" />
      <Input appearance="unstyled" placeholder="Unstyled" />
    </>
  );
}
```

--------------------------------

### Progress Component Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/progress/page.mdx

Demonstrates the basic usage of the Progress component. No specific imports are shown, implying it's used within a framework context.

```javascript
import { Progress } from "@/components";

function App() {
  return <Progress value={50} max={100} />;
}
```

--------------------------------

### Input Component with onChange

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/input/page.mdx

Shows how to use the `onChange` prop for event handling in the Input component.

```javascript
import { Input } from "@optiaxiom/react";

function App() {
  return (
    <Input
      onChange={(e) => console.log(e.target.value)}
      placeholder="Enter text here"
    />
  );
}
```

--------------------------------

### CDN Usage for Axiom Web Components

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/web-components/README.md

Import the package using a CDN. Remember to replace 'latest' with a fixed version number for production environments.

```html
<script
  src="https://cdn.jsdelivr.net/npm/@optiaxiom/web-components@latest/dist/index.js"
  type="module"
></script>
```

--------------------------------

### Menu Basic Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/menu/page.mdx

Demonstrates the basic usage of the Menu component with options.

```tsx
import { Menu, MenuContent, MenuTrigger, MenuOption } from "@optiaxiom/react";

export default () => (
  <Menu
    options={[
      { label: "Item 1" },
      { label: "Item 2" },
      { label: "Item 3" },
    ]}>
    <MenuTrigger />
    <MenuContent />
  </Menu>
);
```

--------------------------------

### DateInput Value Format (Date)

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-input/page.mdx

Example of setting the `value` prop for a `type="date"` DateInput. The expected format is 'YYYY-MM-DD'.

```jsx
import { DateInput } from "@optiaxiom/react";

<DateInput type="date" value="2024-01-01" />
```

--------------------------------

### Initialize AxiomProvider

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/axiom-provider/page.mdx

Render AxiomProvider at the root of your application to provide necessary context managers for Optimizely Axiom React components.

```jsx
import { AxiomProvider } from "@optiaxiom/react";

export function App() {
  return <AxiomProvider>{/* Your app code here */}</AxiomProvider>;
}
```

--------------------------------

### Responsive Styling with Breakpoints and Media Queries

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/page.mdx

Apply styles at various responsive breakpoints using object or array prop notation. Resize the canvas to observe layout changes.

```javascript
import { Demo } from "@/components";
import { Alert } from "@optiaxiom/react";

<Alert intent="warning" mt="16">
  Resize the canvas to see the layout change:
</Alert>

<Demo component="styles/responsive-usage" resizable />
```

--------------------------------

### Remove Box Shadow Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/styling/box-shadow/page.mdx

Illustrates how to remove or disable the box shadow on an element. This is useful for specific design requirements where a shadow is not desired.

```javascript
<Demo component="box-shadow/none-usage" />
```

--------------------------------

### Input Component with Interactive Addons

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/input/page.mdx

Shows how to use interactive elements like icons or buttons as addons for the input component.

```javascript
import { Input, Button, Icon } from "@optiaxiom/react";

function App() {
  return (
    <Input
      addonBefore={<Icon name="search" />}
      addonAfter={<Button variant="ghost">Search</Button>}
      placeholder="Search..."
    />
  );
}
```

--------------------------------

### ModalLayer Usage Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/modal-layer/page.mdx

Wrap third-party portalled components in ModalLayer to ensure they are correctly managed by focus managers within dialogs or popovers.

```javascript
import { ModalLayer } from "@/components";

function MyComponent() {
  return (
    <ModalLayer>
      {/* Content rendered via portal */}
    </ModalLayer>
  );
}
```

--------------------------------

### Import @optimizely/axiom-fonts CSS

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/fonts/page.mdx

Add a bare import statement at the top of your application's entry point to load the fonts CSS. This import must be static and synchronous to ensure fonts are available from first paint and to avoid a flash of fallback fonts.

```tsx
import "@optimizely/axiom-fonts";
```

--------------------------------

### DropdownMenu Addon Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/dropdown-menu/page.mdx

Use the icon, addonBefore, and addonAfter props to add icons, text, or any other element to the start or end of the menu items.

```javascript
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
} from "@optiaxiom/react";
import {
  Archive,
  Trash,
  Pencil,
  Copy,
} from "@optiaxiom/react/icons";

export default (
  <DropdownMenu>
    <DropdownMenuTrigger>Open</DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem addonBefore={<Pencil />} addonAfter="Edit">Edit</DropdownMenuItem>
      <DropdownMenuItem addonBefore={<Copy />} addonAfter="Duplicate">Duplicate</DropdownMenuItem>
      <DropdownMenuItem addonBefore={<Archive />} addonAfter="Archive">Archive</DropdownMenuItem>
      <DropdownMenuItem addonBefore={<Trash />} addonAfter="Delete">Delete</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
);
```

--------------------------------

### Menu Content Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/menu/page.mdx

Shows how to add executable actions to menu items.

```tsx
import { Menu, MenuContent, MenuTrigger, MenuOption } from "@optiaxiom/react";

export default () => (
  <Menu
    options={[
      { label: "Item 1", execute: () => alert("Item 1 clicked") },
      { label: "Item 2", execute: () => alert("Item 2 clicked") },
      { label: "Item 3", execute: () => alert("Item 3 clicked") },
    ]}>
    <MenuTrigger />
    <MenuContent />
  </Menu>
);
```

--------------------------------

### JSDoc for Deprecated Components

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Example of JSDoc comments for marking a component as deprecated. Use `@deprecated` with the version and replacement, and `@see` to point to the replacement component.

```tsx
/**
 * Display a dropdown menu.
 *
 * @since 0.1.0
 * @deprecated since 1.6.0 use {@link Menu} instead
 * @see Menu
 */
export function DropdownMenu(...) { ... }
```

--------------------------------

### Story with Args for Simple Properties

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/storybook/README.md

Illustrates how to define a story using the `args` property for simple component props, such as setting a `disabled` state and `children` content.

```tsx
export const Disabled: Story = {
  args: {
    disabled: true,
    children: "Button",
  },
};
```

--------------------------------

### DateInput Value Format (DateTime)

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/date-input/page.mdx

Example of setting the `value` prop for a `type="datetime-local"` DateInput. The expected format is 'YYYY-MM-DDTHH:MM'.

```jsx
import { DateInput } from "@optiaxiom/react";

<DateInput type="datetime-local" value="2024-01-01T10:30" />
```

--------------------------------

### Basic Usage of OptiAxiom Components

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/guides/page.mdx

Import and use components like Button from the @optiaxiom/react package in your React components.

```jsx
import { Button } from "@optiaxiom/react";

export function MyComponent() {
  return <Button>Hello World!</Button>;
}
```

--------------------------------

### JSDoc for Component Metadata

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/packages/mcp/README.md

Example of JSDoc comments used to generate component metadata. Use `@group` to categorize components and `@since` to specify the version they were introduced.

```tsx
/**
 * Display tabular data using rows and columns.
 *
 * @group Table
 * @since 1.4.0
 */
export const Table = ...
```

--------------------------------

### Field with Different Input Components

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/field/page.mdx

The Field component is versatile and can wrap any form input component, not just the standard Input component. This example shows it with a custom component.

```jsx
import { Field } from "@optimizely/optimizely-ui";
import { MyCustomSelect } from "./MyCustomSelect"; // Assuming MyCustomSelect is a custom component

<Field label="Country" name="country">
  <MyCustomSelect />
</Field>
```

--------------------------------

### FileUpload Anatomy

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/file-upload/page.mdx

Demonstrates the basic structure of the FileUpload component, including the dropzone, trigger, and list areas. This setup is required to enable file selection and preview.

```tsx
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadList,
  FileUploadTrigger,
} from "@optiaxiom/react/unstable";

export default () => (
  <FileUpload>
    <FileUploadDropzone />
    <FileUploadTrigger />
    <FileUploadList />
  </FileUpload>
);
```

--------------------------------

### Story Composition with Spread Syntax

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/storybook/README.md

Demonstrates extending existing stories using the spread syntax (`...`) to inherit properties and `render` functions, allowing for composition and reuse of story definitions.

```tsx
export const Appearance: Story = {
  args: {
    children: "Button",
  },
  render: (args) => (
    <Group flexDirection="column" gap="16">
      <Button {...args} />
      <Button {...args} appearance="primary" />
    </Group>
  ),
};

export const Disabled: Story = {
  ...Appearance, // Inherit render function
  args: {
    children: "Button",
    disabled: true,
  },
};
```

--------------------------------

### Basic Layout Component Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/layout/page.mdx

Demonstrates the fundamental structure of the Layout component. Import Layout and LayoutContent from @optiaxiom/react/unstable to implement a basic page layout.

```tsx
import { Layout, LayoutContent } from "@optiaxiom/react/unstable";

export default () => (
  <Layout>
    <LayoutContent />
  </Layout>
);
```

--------------------------------

### Incorrect Page Structure Example

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/README.md

Avoid placing content directly under an H2 heading. Always use an H3 subsection first to maintain the required page structure.

```mdx
❌ INCORRECT:

## Installation

Add the MCP server to your workspace configuration...
```

--------------------------------

### Toast with Action

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/toast/page.mdx

Include a short action button with a toast by providing the `action` and `onAction` options.

```javascript
toaster.create("Toast with an action.", {
  action: "Undo",
  onAction: () => {
    console.log("Undo action triggered");
  }
})
```

--------------------------------

### Checkbox Usage

Source: https://github.com/optimizely-axiom/optiaxiom/blob/main/apps/docs/app/(docs)/components/checkbox/page.mdx

Demonstrates the basic usage of the Checkbox component.

```javascript
import { Checkbox } from "@/components";

function App() {
  return <Checkbox label="Accept terms" />;
}
```