## 1. Project Overview & Quickstart (statamic/cms)

## File: README.md

## About Statamic

Statamic is the flat-first, Laravel + Git powered CMS designed for building beautiful, easy to manage websites.

> [!NOTE]
> This repository contains the code for the core Statamic Composer package, to be installed into an existing Laravel application. 
> 
> The [application repository][app-repo] is where you can find a Laravel application preconfigured with Statamic, which is used when creating a new project via the Statamic CLI tool.

## Learning Statamic

Statamic has extensive [documentation][docs]. We dedicate a significant amount of time and energy every day to improving them, so if something is unclear, feel free to open issues for anything you find confusing or incomplete. We are happy to consider anything you feel will make the docs and CMS better.

## Support

We provide official developer support on [Statamic Pro](https://statamic.com/pricing) projects. Community-driven support is available on [GitHub Discussions](https://github.com/statamic/cms/discussions) and in [Discord][discord].


## Contributing

Thank you for considering contributing to Statamic! We simply ask that you review the [contribution guide][contribution] before you open issues or send pull requests.


## Code of Conduct

In order to ensure that the Statamic community is welcoming to all and generally a rad place to belong, please review and abide by the [Code of Conduct](https://github.com/statamic/cms/wiki/Code-of-Conduct).


## Important Links

- [Statamic Main Site](https://statamic.com)
- [Statamic Documentation][docs]
- [Statamic Application Repo][app-repo]
- [Statamic Migrator](https://github.com/statamic/migrator)
- [Statamic Discord][discord]

[docs]: https://statamic.dev/
[discord]: https://statamic.com/discord
[contribution]: https://github.com/statamic/cms/blob/master/CONTRIBUTING.md
[app-repo]: https://github.com/statamic/statamic

---

## File: packages/cms/README.md

# @statamic/cms

Statamic CMS companion package to be used for including custom CSS/JSS into the Control Panel.

---

## File: resources/js/stories/docs/Alert.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as AlertStories from '../Alert.stories';

<Meta of={AlertStories} />

# Alert
Alerts are used to display important messages, notifications, and feedback to users. They come in multiple variants to convey different types of information.

<Canvas of={AlertStories._DocsIntro} sourceState={'shown'} />

## Variants
Use the `variant` prop to change the appearance and semantic meaning of the alert. Available variants are `default`, `warning`, `error`, and `success`.

<Canvas of={AlertStories.Variants} sourceState={'shown'} />

## Custom Icons
You can override the default icon by passing a custom `icon` prop with the name of any available icon.

<Canvas of={AlertStories.CustomIcons} sourceState={'shown'} />

## Headings
You can use the `heading` prop to prepend a heading.

<Canvas of={AlertStories.Headings} sourceState={'shown'} />

## Slot Content
Instead of using the `text` and `heading` props, you can use the default slot to provide custom content with HTML formatting.

<Canvas of={AlertStories.SlotContent} sourceState={'shown'} />

## Rich Content
Alerts support rich content including headings, paragraphs, and code snippets, making them ideal for detailed messages and instructions. You can use either native HTML elements (h1–h6, p) or the Heading/Description components—both approaches receive consistent styling and color inheritance.

All heading levels (h1–h6) are styled identically, so choose the heading level that's semantically appropriate for your content. If you want to adjust the size of the headings, you can use the Heading component and specify a size (`base`, `lg`, `xl`, or `2xl`). The Alert component automatically adjusts spacing for larger headings.

<Canvas of={AlertStories.RichContent} sourceState={'shown'} />

## Arguments
<ArgTypes of={AlertStories} />

---

## File: resources/js/stories/docs/Avatar.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as AvatarStories from '../Avatar.stories';

<Meta of={AvatarStories} />

# Avatar
Avatars display user profile images or generated initials with beautiful mesh gradient backgrounds.

<Canvas of={AvatarStories._DocsIntro} sourceState={'shown'} />

The `Avatar` component will use whatever information you pass via the `user` prop to display the user's avatar.

## Arguments
<ArgTypes of={AvatarStories} />

---

## File: resources/js/stories/docs/Badge.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as BadgeStories from '../Badge.stories';

<Meta of={BadgeStories} />

# Badge
Badges are used to display labels, status indicators, counts, and other metadata. They come in many colors and sizes.
<Canvas of={BadgeStories._DocsIntro} sourceState={'shown'} />

## Sizes
Badges are available in multiple sizes via the `size` prop.
<Canvas of={BadgeStories.Sizes} sourceState={'shown'} />

## Colors
Use the `color` prop to change the badge's color.
<Canvas of={BadgeStories.Colors} sourceState={'shown'} />

## Append & Prepend
Use the `append` and `prepend` props to add smaller supporting text before or after the main text, perfect for counts, numbers, and other small details.
<Canvas of={BadgeStories._AppendPrependDocs} sourceState={'shown'} />

## Icons
Automatically sized and styled icons are available for your badges using the `icon` or `icon-append` props to pass the name of an icon.
<Canvas of={BadgeStories._IconDocs} sourceState={'shown'} />

## Pills
Use the `pill` prop to round out the badge.
<Canvas of={BadgeStories.Pill} sourceState={'shown'} />

## As a Link
Badges can be used as links by passing an `href` prop. They will use Inertia to navigate unless you add `target="_blank"` to open in a new tab.
<Canvas of={BadgeStories.Link} sourceState={'shown'} />

## Arguments
<ArgTypes of={BadgeStories} />

---

## File: resources/js/stories/docs/Button.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as ButtonStories from '../Button.stories';

<Meta of={ButtonStories} />

# Button
Buttons are used to trigger actions. They come in many sizes and flavors.
<Canvas of={ButtonStories._DocsIntro} sourceState={'shown'} />

## Variants
Use the `variant` prop to change the appearance of the button.
<Canvas of={ButtonStories.Variants} sourceState={'shown'} />

## Sizes
Use the `size` prop to change the size of the button.
<Canvas of={ButtonStories.Sizes} sourceState={'shown'} />

## Icons
Automatically sized and styled icons are available for your buttons using the `icon` or `icon-append` props. You can also compose your own buttons with icons by nesting an [Icon]() component.
<Canvas of={ButtonStories.Icons} sourceState={'shown'} />

## Round
Round buttons have their place too  -  like Bard set pickers. Just set the `round` prop.
<Canvas of={ButtonStories.Round} sourceState={'shown'} />

## Loading
Show an animated loading icon during network requests.
<Canvas of={ButtonStories.Loading} sourceState={'shown'} />

## Full Width
Fill that container with nothing but button.
<Canvas of={ButtonStories.FullWidth} sourceState={'shown'} />

## As a Link
Buttons can be used as links by passing an `href` prop. They will use Inertia to navigate unless you add `target="_blank"` to open in a new tab.
<Canvas of={ButtonStories.Link} sourceState={'shown'} />

## Inset
When using `ghost` or `subtle` button variants, you can use the `inset` prop to remove any invisible padding for better alignment.
<Canvas of={ButtonStories.Inset} sourceState={'shown'} />

## Button Groups
You can combine multiple buttons into a "button group".
<Canvas of={ButtonStories.ButtonGroups} sourceState={'shown'} />

### Overflow
By default, button groups don't handle overflow. Use the `overflow` prop to opt in to responsive behavior.

Use `overflow="stack"` to switch to a vertical layout when buttons don't fit on one line.
<Canvas of={ButtonStories.ButtonGroupOverflowStack} sourceState={'shown'} />

Use `overflow="gap"` to switch to separated buttons with gaps.
<Canvas of={ButtonStories.ButtonGroupOverflowGap} sourceState={'shown'} />

## Arguments
<ArgTypes of={ButtonStories} />

---

## File: resources/js/stories/docs/Calendar.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as CalendarStories from '../Calendar.stories';

<Meta of={CalendarStories} />

# Calendar
We'll give you 3 guesses what this is for.
<Canvas of={CalendarStories._DocsIntro} sourceState={'shown'} />

## Multiple Months
You can pass the `number-of-months` prop to display multiple months at once.
<Canvas of={CalendarStories._MultipleMonths} sourceState={'shown'} />

## Week Starts On
You can pass the `week-starts-on` prop to change the first day of the week.

The default is `0` (Sunday). Monday is `1`, Tuesday is `2`, etc.
<Canvas of={CalendarStories._WeekStartsOn} sourceState={'shown'} />

## Arguments
<ArgTypes of={CalendarStories} />

---

## File: resources/js/stories/docs/Card.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as CardStories from '../Card.stories';

<Meta of={CardStories} />

# Card
The ubiquitous container of all elements! The div of any component system. Cards can contain anything you want – content, widgets, settings, forms, you name it.
<Canvas of={CardStories._DocsIntro} sourceState={'shown'} />

## Inset
Remove all the inner padding to set the content flush to the sides with the `inset` prop.
<Canvas of={CardStories._Inset} sourceState={'shown'} />

## Variants
Use the `variant` prop to change the appearance of the card.
<Canvas of={CardStories._Variants} sourceState={'shown'} />

## Card Panels
Card panels are one of the most common patterns throughout our UI system. They help create visual context to your interfaces and help break up long forms.
<Canvas of={CardStories._CardPanel} sourceState={'shown'} />

## Composing Card Panels
The UI Kit's components are designed to be composable. You can create your own unique card panels by combining smaller components however you wish, even mixing in your own HTML, CSS, and/or Tailwind.
<Canvas of={CardStories._Composed} sourceState={'shown'} />

## Arguments
<ArgTypes of={CardStories} />

---

## File: resources/js/stories/docs/CharacterCounter.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as CharacterCounterStories from '../CharacterCounter.stories';

<Meta of={CharacterCounterStories} />

# CharacterCounter
A visual character counter that displays as a circular progress indicator. The counter changes color based on how close you are to the limit and shows a countdown when nearing the maximum. Typically used with text inputs and textareas.
<Canvas of={CharacterCounterStories._DocsIntro} sourceState={'shown'} />

## With Input
The CharacterCounter is automatically displayed when you set a `limit` prop on Input or Textarea components. No need to manually add the CharacterCounter component.
<Canvas of={CharacterCounterStories._WithInput} sourceState={'shown'} />

## States
The counter provides visual feedback with different colors based on character usage:
- **Green**: Under 70% of the limit
- **Amber**: Between 70-90% of the limit  
- **Red**: Between 90-100% of the limit
- **Red with strike**: Over the limit

Hover over the counter to see the exact character count.
<Canvas of={CharacterCounterStories._States} sourceState={'shown'} />

## Danger Zone
Use the `danger-zone` prop to control when the remaining character countdown appears. By default, it shows when 20 or fewer characters remain.
<Canvas of={CharacterCounterStories._DangerZone} sourceState={'shown'} />

## Arguments
<ArgTypes of={CharacterCounterStories} />

---

## File: resources/js/stories/docs/Checkbox.mdx

import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
import * as CheckboxStories from '../Checkbox.stories';

<Meta of={CheckboxStories} />

# Checkbox
A checkbox input component with label and description support. Can be used individually or as part of a checkbox group.
<Canvas of={CheckboxStories._DocsIntro} sourceState={'shown'} />

## With Description
<Canvas of={CheckboxStories.WithDescription} sourceState={'shown'} />

## Sizes
<Canvas of={CheckboxStories.Sizes} sourceState={'shown'} />

## Disabled
<Canvas of={CheckboxStories.Disabled} sourceState={'shown'} />

## Solo Mode
Use `solo` when the checkbox is used in a context where the label is provided elsewhere, like in a table cell. The label is still required for accessibility but won't be visually displayed:
<Canvas of={CheckboxStories.Solo} sourceState={'shown'} />

## Checkbox Group
Group multiple checkboxes together with `CheckboxGroup`. The group manages the selected values as an array:
<Canvas of={CheckboxStories.Group} sourceState={'shown'} />

## Inline Group
Use the `inline` prop to display checkboxes horizontally:
<Canvas of={CheckboxStories.InlineGroup} sourceState={'shown'} />

## Arguments
<ArgTypes of={CheckboxStories} />

## 2. Official Technical Reference & Guides (statamic/docs)

## Statamic Documentation

This is the source of the official [Statamic docs][docs].


## Local Development

If you want to work on this project on your local machine, you may follow the instructions below. These instructions assume you are serving the site using [Laravel Valet](https://laravel.com/docs/valet) out of your `~/Sites` directory:

1. Fork this repository
2. Open your terminal and cd to your `~/Sites` folder
3. Clone your fork into the `~/Sites/docs` folder, by running the following command with your username placed into the {username} slot:
    ```
    git clone git@github.com:{username}/docs statamic-docs
    ```
4. CD into the new directory you just created.
5. Run the following commands:
  ```
  composer install
  npm install
  npm run dev
  cp .env.example .env
  php artisan key:generate
  ```

## Providing Feedback

We love it when people provide thoughtful feedback! Feel free to open issues on for any content you find confusing or incomplete. We are happy to consider anything you feel will make the docs and CMS better.


## Contributing

Thank you for considering contributing to Statamic! Every page in the [docs site](https://statamic.dev) has a link at the bottom that will take you right to the exact content file that renders the page. Click the edit button and submit those PRs!

**We simply ask that you please review the [contribution guide][contribution] before you send pull requests.**


## Code of Conduct

In order to ensure that the Statamic community is welcoming to all and generally a rad place to belong, please review and abide by the [Code of Conduct](https://github.com/statamic/cms/wiki/Code-of-Conduct).


## Important Links

- [Statamic Main Site](https://statamic.com)
- [Statamic Documentation][docs]
- [Statamic CMS Repo][cms-repo] (that we maintain)
- [Statamic Application Repo][app-repo] (that you clone)
- [Statamic Migrator](https://github.com/statamic/migrator)
- [Statamic Discord][discord]

[docs]: https://statamic.dev/
[discord]: https://statamic.com/discord
[contribution]: https://github.com/statamic/cms/blob/master/CONTRIBUTING.md
[app-repo]: https://github.com/statamic/statamic
[cms-repo]: https://github.com/statamic/cms