@12-apps/ui 1.0.0

package/src/components/typography/Heading/Heading.tsx

@@ -0,0 +1,178 @@
+import type { Theme } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import type { HeadingProps } from './Heading.types';
+
+const getColorFromTheme = (theme: Theme, color: string) => {
+  if (color === 'neutral') {
+    return theme.palette.text.primary;
+  }
+
+  const colorMap: Record<string, string> = {
+    primary: theme.palette.primary.main,
+    secondary: theme.palette.secondary.main,
+    success: theme.palette.success.main,
+    warning: theme.palette.warning.main,
+    danger: theme.palette.error.main,
+  };
+
+  return colorMap[color] || theme.palette.text.primary;
+};
+
+// Create styled versions of each heading element
+const createStyledHeading = () =>
+  styled('h1', {
+    shouldForwardProp: (prop) =>
+      !['customLevel', 'customColor', 'customWeight', 'gradient'].includes(prop as string),
+  })<{
+    customLevel?: string;
+    customColor?: string;
+    customWeight?: string;
+    gradient?: boolean;
+  }>(({ theme, customLevel = 'h2', customColor = 'neutral', customWeight = 'bold', gradient }) => {
+    const textColor = getColorFromTheme(theme, customColor);
+
+    // Weight mapping
+    const weightMap = {
+      light: 300,
+      normal: 400,
+      medium: 500,
+      semibold: 600,
+      bold: 700,
+    };
+
+    // Level-specific styles
+    const levelStyles = {
+      h1: {
+        fontSize: '3rem',
+        lineHeight: 1.1,
+        letterSpacing: '-0.02em',
+        fontWeight:
+          customWeight === 'normal' ? 700 : weightMap[customWeight as keyof typeof weightMap],
+      },
+      h2: {
+        fontSize: '2.5rem',
+        lineHeight: 1.2,
+        letterSpacing: '-0.015em',
+        fontWeight:
+          customWeight === 'normal' ? 700 : weightMap[customWeight as keyof typeof weightMap],
+      },
+      h3: {
+        fontSize: '2rem',
+        lineHeight: 1.25,
+        letterSpacing: '-0.01em',
+        fontWeight:
+          customWeight === 'normal' ? 600 : weightMap[customWeight as keyof typeof weightMap],
+      },
+      h4: {
+        fontSize: '1.5rem',
+        lineHeight: 1.3,
+        letterSpacing: '-0.005em',
+        fontWeight:
+          customWeight === 'normal' ? 600 : weightMap[customWeight as keyof typeof weightMap],
+      },
+      h5: {
+        fontSize: '1.25rem',
+        lineHeight: 1.4,
+        fontWeight:
+          customWeight === 'normal' ? 600 : weightMap[customWeight as keyof typeof weightMap],
+      },
+      h6: {
+        fontSize: '1.125rem',
+        lineHeight: 1.4,
+        fontWeight:
+          customWeight === 'normal' ? 600 : weightMap[customWeight as keyof typeof weightMap],
+      },
+      display: {
+        fontSize: '4rem',
+        lineHeight: 0.95,
+        letterSpacing: '-0.03em',
+        fontWeight:
+          customWeight === 'normal' ? 800 : weightMap[customWeight as keyof typeof weightMap],
+      },
+    };
+
+    const baseStyles = {
+      fontFamily: theme.typography.h1.fontFamily,
+      margin: 0,
+      transition: 'all 0.2s ease',
+      ...levelStyles[customLevel as keyof typeof levelStyles],
+    };
+
+    // Gradient text effect
+    if (gradient) {
+      const gradientColor =
+        customColor === 'primary'
+          ? `linear-gradient(135deg, ${theme.palette.primary.main} 0%, ${theme.palette.secondary.main} 100%)`
+          : customColor === 'secondary'
+            ? `linear-gradient(135deg, ${theme.palette.secondary.main} 0%, ${theme.palette.primary.main} 100%)`
+            : customColor === 'success'
+              ? `linear-gradient(135deg, ${theme.palette.success.light} 0%, ${theme.palette.success.dark} 100%)`
+              : customColor === 'warning'
+                ? `linear-gradient(135deg, ${theme.palette.warning.light} 0%, ${theme.palette.warning.dark} 100%)`
+                : customColor === 'danger'
+                  ? `linear-gradient(135deg, ${theme.palette.error.light} 0%, ${theme.palette.error.dark} 100%)`
+                  : `linear-gradient(135deg, ${theme.palette.primary.main} 0%, ${theme.palette.secondary.main} 100%)`;
+
+      return {
+        ...baseStyles,
+        background: gradientColor,
+        backgroundClip: 'text',
+        WebkitBackgroundClip: 'text',
+        WebkitTextFillColor: 'transparent',
+        MozBackgroundClip: 'text',
+        MozTextFillColor: 'transparent',
+      };
+    }
+
+    return {
+      ...baseStyles,
+      color: textColor,
+    };
+  });
+
+// Create styled components for each heading level
+const StyledH1 = createStyledHeading().withComponent('h1');
+const StyledH2 = createStyledHeading().withComponent('h2');
+const StyledH3 = createStyledHeading().withComponent('h3');
+const StyledH4 = createStyledHeading().withComponent('h4');
+const StyledH5 = createStyledHeading().withComponent('h5');
+const StyledH6 = createStyledHeading().withComponent('h6');
+
+export const Heading = React.forwardRef<globalThis.HTMLHeadingElement, HeadingProps>(
+  (
+    { level = 'h2', color = 'neutral', weight = 'bold', gradient = false, children, ...props },
+    ref,
+  ) => {
+    const commonProps = {
+      ref,
+      customLevel: level,
+      customColor: color,
+      customWeight: weight,
+      gradient,
+      ...props,
+    };
+
+    // Return the appropriate styled heading component based on level
+    switch (level) {
+      case 'h1':
+      case 'display':
+        return <StyledH1 {...commonProps}>{children}</StyledH1>;
+      case 'h2':
+        return <StyledH2 {...commonProps}>{children}</StyledH2>;
+      case 'h3':
+        return <StyledH3 {...commonProps}>{children}</StyledH3>;
+      case 'h4':
+        return <StyledH4 {...commonProps}>{children}</StyledH4>;
+      case 'h5':
+        return <StyledH5 {...commonProps}>{children}</StyledH5>;
+      case 'h6':
+        return <StyledH6 {...commonProps}>{children}</StyledH6>;
+      default:
+        return <StyledH2 {...commonProps}>{children}</StyledH2>;
+    }
+  },
+);
+
+Heading.displayName = 'Heading';

package/src/components/typography/Heading/Heading.types.ts

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display';
+
+export interface HeadingProps extends React.HTMLAttributes<globalThis.HTMLHeadingElement> {
+  level?: HeadingLevel;
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral';
+  weight?: 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+  gradient?: boolean;
+  children: React.ReactNode;
+}

package/src/components/typography/Heading/index.ts

@@ -0,0 +1,2 @@
+export { Heading } from './Heading';
+export type { HeadingLevel,HeadingProps } from './Heading.types';

package/src/components/typography/Paragraph/Paragraph.md

@@ -0,0 +1,80 @@
+# Paragraph Component
+
+A semantic paragraph component with multiple visual variants for different content contexts. Features lead text styling, muted text, small text, and configurable sizing options. Optimized for readability with proper line height and typography scaling across different use cases.
+
+## Purpose and Use Cases
+
+- Standard paragraph text in body content
+- Lead paragraphs for article introductions and emphasis  
+- Muted secondary text for supporting content
+- Small text for captions, footnotes, and fine print
+- Scalable typography that maintains readability across different sizes
+
+## Props
+
+### `variant?: ParagraphVariant`
+- **Type:** `'default' | 'lead' | 'muted' | 'small'`
+- **Default:** `'default'`
+- **Description:** Text style variant
+  - `default`: Standard paragraph styling
+  - `lead`: Emphasized intro text with larger font and enhanced spacing
+  - `muted`: Secondary text with reduced opacity
+  - `small`: Smaller text for captions and fine print
+
+### `color?: string`
+- **Type:** `'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral'`
+- **Default:** `'neutral'`
+- **Description:** Theme color for the text
+
+### `size?: string`
+- **Type:** `'xs' | 'sm' | 'md' | 'lg' | 'xl'`
+- **Default:** `'md'`
+- **Description:** Size scaling for the paragraph text
+
+### `children: React.ReactNode`
+- **Required:** Yes
+- **Description:** The paragraph content to render
+
+## Usage Examples
+
+### Basic Paragraph
+```tsx
+<Paragraph>
+  This is a standard paragraph with default styling.
+</Paragraph>
+```
+
+### Lead Paragraph
+```tsx
+<Paragraph variant="lead">
+  This is a lead paragraph used for article introductions with enhanced typography.
+</Paragraph>
+```
+
+### Color and Size Variations
+```tsx
+<Paragraph color="primary" size="lg">
+  A larger primary-colored paragraph.
+</Paragraph>
+
+<Paragraph variant="muted" size="sm">
+  A smaller muted paragraph for supporting content.
+</Paragraph>
+```
+
+## Accessibility Notes
+
+- Uses semantic `<p>` element for proper document structure
+- Maintains appropriate color contrast ratios
+- Supports screen readers with proper text semantics
+- Line height optimized for readability across all sizes
+- Respects user font size preferences
+
+## Best Practices
+
+- Use `variant="lead"` sparingly for emphasis and introductions
+- Apply `variant="muted"` to secondary content that supports main text
+- Choose appropriate `size` values that maintain readability
+- Ensure sufficient color contrast when using colored variants
+- Keep paragraph length reasonable for good readability (typically 45-75 characters per line)
+- Use consistent margin and spacing with other typography elements

package/src/components/typography/Paragraph/Paragraph.stories.tsx

@@ -0,0 +1,280 @@
+import { Box,Paper, Stack } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Paragraph } from './Paragraph';
+
+const meta: Meta<typeof Paragraph> = {
+  title: 'Typography/Paragraph',
+  component: Paragraph,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'A semantic paragraph component with multiple visual variants for different content contexts. Features lead text styling, muted text, small text, and configurable sizing options.',
+      },
+    },
+  },
+  tags: ['autodocs', 'component:Paragraph'],
+  argTypes: {
+    variant: {
+      control: { type: 'select' },
+      options: ['default', 'lead', 'muted', 'small'],
+      description: 'Paragraph style variant',
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'success', 'warning', 'danger', 'neutral'],
+      description: 'Theme color',
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Size variant',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const sampleText = `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.`;
+
+const longText = `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.`;
+
+export const Default: Story = {
+  args: {
+    children: sampleText,
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Default Paragraph</h4>
+          <Paragraph variant="default">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Lead Paragraph</h4>
+          <Paragraph variant="lead">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Small Paragraph</h4>
+          <Paragraph variant="small">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Muted Paragraph</h4>
+          <Paragraph variant="muted">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Extra Small (xs)</h4>
+          <Paragraph size="xs">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Small (sm)</h4>
+          <Paragraph size="sm">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Medium (md) - Default</h4>
+          <Paragraph size="md">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Large (lg)</h4>
+          <Paragraph size="lg">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Extra Large (xl)</h4>
+          <Paragraph size="xl">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Neutral (default)</h4>
+          <Paragraph color="neutral">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Primary Color</h4>
+          <Paragraph color="primary">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Secondary Color</h4>
+          <Paragraph color="secondary">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Success Color</h4>
+          <Paragraph color="success">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Warning Color</h4>
+          <Paragraph color="warning">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Danger Color</h4>
+          <Paragraph color="danger">{sampleText}</Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const InteractiveStates: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 3 }}>
+          <h3>Article Example</h3>
+          <Paragraph variant="lead" size="lg" color="primary">
+            This is a lead paragraph with large size and primary color. It's designed to grab
+            attention and introduce the main content.
+          </Paragraph>
+
+          <Paragraph>
+            This is a regular paragraph that follows the lead paragraph. It uses default styling for
+            comfortable reading.
+          </Paragraph>
+
+          <Paragraph variant="small" color="secondary">
+            This is a small paragraph with secondary color, often used for additional information or
+            footnotes.
+          </Paragraph>
+
+          <Paragraph variant="muted">
+            This is a muted paragraph that provides supplementary information without competing for
+            attention.
+          </Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const Responsive: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 2 }}>
+          <h4>Responsive Behavior</h4>
+          <Paragraph
+            sx={{
+              fontSize: { xs: '14px', sm: '16px', md: '18px' },
+              lineHeight: { xs: 1.5, md: 1.7 },
+            }}
+          >
+            This paragraph adjusts its font size and line height based on screen size for optimal
+            readability across devices.
+          </Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};
+
+// Additional helpful stories
+export const LongContent: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 3 }}>
+          <h4>Long Content Handling</h4>
+          <Paragraph variant="lead">{longText}</Paragraph>
+
+          <Paragraph>{longText}</Paragraph>
+
+          <Paragraph variant="small">{longText}</Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const WithCustomStyling: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <Box>
+        <Paper sx={{ p: 3 }}>
+          <h4>Custom Styling Examples</h4>
+          <Paragraph
+            variant="lead"
+            sx={{
+              textAlign: 'center',
+              background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
+              WebkitBackgroundClip: 'text',
+              WebkitTextFillColor: 'transparent',
+              backgroundClip: 'text',
+            }}
+          >
+            This paragraph demonstrates custom styling with gradient text and center alignment.
+          </Paragraph>
+
+          <Paragraph
+            sx={{
+              border: '1px solid',
+              borderColor: 'divider',
+              borderRadius: 2,
+              p: 2,
+              backgroundColor: 'grey.50',
+            }}
+          >
+            This paragraph has a custom border and background, making it stand out from the rest of
+            the content.
+          </Paragraph>
+        </Paper>
+      </Box>
+    </Stack>
+  ),
+};