feat: move storybook to the root

.storybook/main.js

@@ -1,5 +1,10 @@
 const config = {
-  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  stories: [
+    '../storybook/**/*.mdx',
+    '../storybook/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+    '../src/**/*.mdx',
+    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+  ],
   addons: [
     '@storybook/addon-links',
     '@storybook/addon-essentials',

storybook/README.md

@@ -0,0 +1,60 @@
+# Newspack UI Storybook
+
+This directory contains the Storybook implementation for Newspack UI components. Storybook is a development environment for UI components, allowing you to browse a component library, view the different states of each component, and interactively develop and test components.
+
+## Running Storybook
+
+From the plugin root directory:
+
+```bash
+npm run storybook
+```
+
+This will open Storybook in your default browser at `http://localhost:6006`.
+
+## Project Structure
+
+```
+newspack-plugin/
+├── storybook/
+│   ├── button/
+│   │   ├── index.stories.js   # Button stories
+│   │   └── docs.mdx          # Button documentation
+│   ├── segmented-control/
+│   │   ├── index.stories.js
+│   │   └── docs.mdx
+│   └── README.md             # This file
+└── src/
+    └── newspack-ui/
+        ├── scss/            # Component styles
+        └── style.scss       # Main stylesheet
+```
+
+## Available Scripts
+
+- `npm run storybook` - Start Storybook development server
+- `npm run build-storybook` - Build static Storybook for deployment
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Storybook fails to start**
+   - Check Node.js version
+   - Clear npm cache: `npm cache clean --force`
+   - Delete node_modules and reinstall: `rm -rf node_modules && npm install`
+
+2. **Stories not appearing**
+   - Verify file naming follows conventions
+   - Check story export format
+   - Clear Storybook cache: `rm -rf node_modules/.cache/storybook`
+
+3. **Styles not loading**
+   - Verify style imports
+   - Check webpack configuration
+   - Clear browser cache
+
+## Resources
+
+- [Storybook Documentation](https://storybook.js.org/docs)
+- [MDX Documentation](https://mdxjs.com/docs/)

storybook/button/docs.mdx

@@ -0,0 +1,70 @@
+import { Meta, Canvas } from '@storybook/blocks';
+import * as ButtonStories from './index.stories';
+
+<Meta of={ButtonStories} name="Docs" />
+
+# Button
+
+A button component that provides a consistent look and feel across the Newspack UI.
+
+<Canvas of={ButtonStories.Primary} sourceState="shown" />
+<Canvas of={ButtonStories.Secondary} sourceState="shown" />
+<Canvas of={ButtonStories.Branded} sourceState="shown" />
+<Canvas of={ButtonStories.Ghost} sourceState="shown" />
+<Canvas of={ButtonStories.Outline} sourceState="shown" />
+<Canvas of={ButtonStories.Destructive} sourceState="shown" />
+<Canvas of={ButtonStories.IconOnly} sourceState="shown" />
+
+## CSS Classes
+
+- `.newspack-ui`: Root namespace for Newspack UI components
+- `.newspack-ui__button`: Base button class
+- `.newspack-ui__button__label`: Container for button text
+- `.newspack-ui__button__glyph`: Container for button icon
+
+### Modifiers
+- `.newspack-ui__button--primary`: Main call-to-action buttons
+- `.newspack-ui__button--secondary`: Supporting actions (default)
+- `.newspack-ui__button--branded`: Special emphasis using brand colors
+- `.newspack-ui__button--ghost`: Subtle actions that don't need strong visual emphasis
+- `.newspack-ui__button--outline`: Actions that need structure but minimal visual weight
+- `.newspack-ui__button--destructive`: Actions with destructive consequences
+- `.newspack-ui__button--x-small`: Extra small button size
+- `.newspack-ui__button--small`: Small button size
+- `.newspack-ui__button--medium`: Default button size
+- `.newspack-ui__button--wide`: Makes the button take full width of its container
+- `.newspack-ui__button--icon`: Styles the button as an icon-only button
+- `.newspack-ui__button--loading`: Shows a loading spinner and hides button content
+
+## Usage Guidelines
+
+### Button Variants
+- `primary`: Main call-to-action buttons
+- `secondary`: Supporting actions (default)
+- `branded`: Special emphasis using brand colors
+- `ghost`: Subtle actions that don't need strong visual emphasis
+- `outline`: Actions that need structure but minimal visual weight
+- `destructive`: Actions with destructive consequences
+
+### Button Size
+- `medium` (default): Suitable for most use cases
+- `small`: Use in secondary interfaces or when you need slightly reduced prominence
+- `x-small`: Use in compact interfaces where space is limited
+
+### Layout Options
+- Default: Button will size to its content
+- `wide`: Makes the button take full width of its container
+- `icon`: Styles the button as an icon-only button
+- `loading`: Shows a loading spinner and hides button content
+
+## Accessibility
+
+1. **Keyboard Navigation**:
+   - Ensure buttons are focusable using Tab key
+   - Use Enter or Space to activate buttons
+   - Maintain a logical tab order
+
+2. **ARIA Attributes**:
+   - Use `aria-label` for icon-only buttons
+   - Use `aria-disabled="true"` when disabled
+   - Use `aria-pressed` for toggle buttons

src/newspack-ui/storyboard/button/index.stories.js → storybook/button/index.stories.js

@@ -1,5 +1,5 @@
 import React from 'react';
-import '../../style.scss';
+import '../../src/newspack-ui/style.scss';
 
 export default {
   title: 'Newspack UI/Button',