feat: move storybook to the root and add readme

.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,42 @@
+# 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`.
+
+## 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',

src/newspack-ui/storyboard/segmented-control/docs.mdx → storybook/segmented-control/docs.mdx

@@ -9,29 +9,9 @@ A segmented control provides a tabbed interface for switching between different
 
 <Canvas of={SegmentedControlStories.Default} sourceState="shown" />
 
-## Usage Guidelines
-
-### HTML Structure
-
-```html
-<div class="newspack-ui">
-  <div class="newspack-ui__segmented-control">
-    <div class="newspack-ui__segmented-control__tabs">
-      <button class="newspack-ui__button">Last 7 Days</button>
-      <button class="newspack-ui__button selected">Last 30 Days</button>
-      <button class="newspack-ui__button">Last Quarter</button>
-    </div>
-    <div class="newspack-ui__segmented-control__content">
-      <div class="newspack-ui__segmented-control__panel">Last 7 days content</div>
-      <div class="newspack-ui__segmented-control__panel selected">Last 30 days content</div>
-      <div class="newspack-ui__segmented-control__panel">Last quarter content</div>
-    </div>
-  </div>
-</div>
-```
-
-### CSS Classes
+## CSS Classes
 
+### Base Classes
 - `.newspack-ui`: Root namespace for Newspack UI components
 - `.newspack-ui__segmented-control`: Container for the entire component
 - `.newspack-ui__segmented-control__tabs`: Container for tab buttons
@@ -40,16 +20,22 @@ A segmented control provides a tabbed interface for switching between different
 - `.newspack-ui__segmented-control__content`: Container for panel content
 - `.newspack-ui__segmented-control__panel`: Individual content panel
 
-### When to Use Each Options
+### Modifiers
+- `.newspack-ui__segmented-control--wide`: Makes the control full-width with equal-width buttons
+- `.newspack-ui__button--x-small`: Extra small button size
+- `.newspack-ui__button--small`: Small button size
+- `.newspack-ui__button--medium`: Default button size
+
+## Usage Guidelines
 
-1. **Button Size**:
-   - `x-small`: Use in compact interfaces where space is limited
-   - `small`: Use in secondary interfaces or when you need slightly reduced prominence
-   - `medium`: Default size, suitable for most use cases
+### 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
 
-2. **Layout Options**:
-   - `full-width`: Use when the control should span the entire container width, typically on mobile or in narrow layouts
-   - `equal-width`: Use when button labels are similar in length or when you need a more uniform appearance
+### Layout
+- Default: Buttons will size to their content
+- `wide`: Use when you want the control to span the full width and have equal-width buttons, typically on mobile or in narrow layouts
 
 ## Accessibility
 

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

@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import '../../style.scss';
+import '../../src/newspack-ui/style.scss';
 
 /**
  * The Segmented Control component provides a tabbed interface for switching between different views or options.
@@ -11,6 +11,43 @@ export default {
     backgrounds: {
       default: 'light',
     },
+    docs: {
+      source: {
+        transform: (_, story) => {
+          const args = story.args;
+          const segmentedControlClasses = ['newspack-ui__segmented-control'];
+          const buttonClasses = ['newspack-ui__button'];
+
+          if (args.size && args.size !== 'medium') {
+            buttonClasses.push(`newspack-ui__button--${args.size}`);
+          }
+          if (args.isWide) {
+            segmentedControlClasses.push('newspack-ui__segmented-control--wide');
+          }
+
+          return `<div class="newspack-ui">
+  <div class="${segmentedControlClasses.join(' ')}">
+    <div class="newspack-ui__segmented-control__tabs">
+      <button class="${buttonClasses.join(' ')} selected">Last 7 Days</button>
+      <button class="${buttonClasses.join(' ')}">Last 30 Days</button>
+      <button class="${buttonClasses.join(' ')}">Last Quarter</button>
+    </div>
+    <div class="newspack-ui__segmented-control__content">
+      <div class="newspack-ui__segmented-control__panel selected">
+        Showing analytics data for the past 7 days. This is a shorter time range that helps identify recent trends.
+      </div>
+      <div class="newspack-ui__segmented-control__panel">
+        Displaying analytics for the past month. This provides a broader view of your site's performance.
+      </div>
+      <div class="newspack-ui__segmented-control__panel">
+        Quarterly view of analytics data. Use this to understand long-term patterns and seasonal changes.
+      </div>
+    </div>
+  </div>
+</div>`;
+        },
+      },
+    },
   },
   argTypes: {
     size: {
@@ -23,22 +60,13 @@ export default {
         type: { summary: 'CSS class: newspack-ui__button--{size}' },
       },
     },
-    isFullWidth: {
-      description: 'Whether the segmented control should take full width',
+    isWide: {
+      description: 'Whether the segmented control should take full width with equal-width buttons',
       control: 'boolean',
       defaultValue: false,
       table: {
         defaultValue: { summary: false },
-        type: { summary: 'CSS class: newspack-ui__segmented-control--full-width' },
-      },
-    },
-    hasEqualWidth: {
-      description: 'Whether the buttons should have equal width',
-      control: 'boolean',
-      defaultValue: false,
-      table: {
-        defaultValue: { summary: false },
-        type: { summary: 'CSS class: newspack-ui__segmented-control__tabs--equal-width' },
+        type: { summary: 'CSS class: newspack-ui__segmented-control--wide' },
       },
     },
   },
@@ -61,18 +89,14 @@ const getSegmentedControlClasses = (args) => {
   if (args.size && args.size !== 'medium') {
     classes.push(`newspack-ui__segmented-control--${args.size}`);
   }
-  if (args.isFullWidth) {
-    classes.push('newspack-ui__segmented-control--full-width');
+  if (args.isWide) {
+    classes.push('newspack-ui__segmented-control--wide');
   }
   return classes.filter(Boolean).join(' ');
 };
 
-const getTabsClasses = (args) => {
-  const classes = ['newspack-ui__segmented-control__tabs'];
-  if (args.hasEqualWidth) {
-    classes.push('newspack-ui__segmented-control__tabs--equal-width');
-  }
-  return classes.join(' ');
+const getTabsClasses = () => {
+  return 'newspack-ui__segmented-control__tabs';
 };
 
 const getButtonClasses = (isSelected, size) => {
@@ -107,7 +131,7 @@ const SegmentedControlStory = (args) => {
     <StoryWrapper>
       <div className="newspack-ui">
         <div className={getSegmentedControlClasses(args)}>
-          <div className={getTabsClasses(args)}>
+          <div className={getTabsClasses()}>
             {tabs.map((tab, index) => (
               <button
                 key={tab.label}
@@ -138,8 +162,7 @@ const SegmentedControlStory = (args) => {
 export const Default = {
   args: {
     size: 'medium',
-    isFullWidth: false,
-    hasEqualWidth: false,
+    isWide: false,
   },
   render: SegmentedControlStory,
 };