@discourser/design-system 0.9.3 → 0.9.4

package/src/stories/foundations/Spacing.mdx

@@ -0,0 +1,223 @@
+import { Meta } from '@storybook/blocks';
+import { SpacingBox } from './components/SpacingBox';
+import { material3Language } from '../../languages/material3.language';
+
+<Meta title="Foundations/Spacing" />
+
+# Spacing
+
+The Discourser Design System uses a consistent spacing scale based on an 8-point grid system. This creates visual rhythm and helps maintain consistent layouts across all components and screens.
+
+## Spacing Scale
+
+Our spacing scale ranges from `none` (0px) to `xxxl` (64px), with incremental steps that follow a logical progression.
+
+<div style={{ marginTop: '32px', marginBottom: '48px' }}>
+  <SpacingBox name="none" value={material3Language.spacing.none} />
+  <SpacingBox name="xxs" value={material3Language.spacing.xxs} />
+  <SpacingBox name="xs" value={material3Language.spacing.xs} />
+  <SpacingBox name="sm" value={material3Language.spacing.sm} />
+  <SpacingBox name="md" value={material3Language.spacing.md} />
+  <SpacingBox name="lg" value={material3Language.spacing.lg} />
+  <SpacingBox name="xl" value={material3Language.spacing.xl} />
+  <SpacingBox name="xxl" value={material3Language.spacing.xxl} />
+  <SpacingBox name="xxxl" value={material3Language.spacing.xxxl} />
+</div>
+
+---
+
+## Spacing Reference Table
+
+| Token | Value | Pixels | Use Case |
+|-------|-------|--------|----------|
+| `none` | {material3Language.spacing.none} | 0px | Reset spacing, remove gaps |
+| `xxs` | {material3Language.spacing.xxs} | 2px | Minimal gaps, fine-tuning |
+| `xs` | {material3Language.spacing.xs} | 4px | Tight spacing within components |
+| `sm` | {material3Language.spacing.sm} | 8px | Component internal spacing |
+| `md` | {material3Language.spacing.md} | 16px | Default spacing, component gaps |
+| `lg` | {material3Language.spacing.lg} | 24px | Section spacing, card padding |
+| `xl` | {material3Language.spacing.xl} | 32px | Large section breaks |
+| `xxl` | {material3Language.spacing.xxl} | 48px | Major section dividers |
+| `xxxl` | {material3Language.spacing.xxxl} | 64px | Page-level spacing |
+
+---
+
+## Usage Guidelines
+
+### Common Patterns
+
+**Component Internal Spacing**
+- Icon-to-text gap: `xs` (4px) or `sm` (8px)
+- Button padding: `sm` (8px) vertical, `md` (16px) horizontal
+- Input padding: `md` (16px)
+
+**Component Gaps**
+- Between related items: `sm` (8px) or `md` (16px)
+- Between form fields: `md` (16px) or `lg` (24px)
+- Between sections: `lg` (24px) to `xxl` (48px)
+
+**Layout Spacing**
+- Card padding: `lg` (24px) or `xl` (32px)
+- Section margins: `xl` (32px) or `xxl` (48px)
+- Page margins: `xxl` (48px) or `xxxl` (64px)
+
+### The 8-Point Grid
+
+Most of our spacing values are multiples of 8px, which:
+- Creates visual consistency
+- Simplifies spacing decisions
+- Works well with common screen sizes
+- Aligns with Material Design principles
+
+The exceptions (`xxs: 2px`) are provided for fine-tuning and edge cases.
+
+### Responsive Spacing
+
+Consider adjusting spacing at different breakpoints:
+
+```tsx
+import { css } from 'styled-system/css';
+
+const containerStyle = css({
+  padding: {
+    base: 'md',  // 16px on mobile
+    md: 'lg',    // 24px on tablet
+    lg: 'xl'     // 32px on desktop
+  }
+});
+```
+
+### Negative Space
+
+Empty space is just as important as filled space. Use larger spacing values to:
+- Create visual breathing room
+- Establish content hierarchy
+- Guide user attention
+- Improve scannability
+
+---
+
+## Example Usage
+
+### Padding
+
+```tsx
+import { css } from 'styled-system/css';
+
+// Card padding
+const cardStyle = css({
+  padding: 'lg'  // 24px all sides
+});
+
+// Asymmetric padding
+const headerStyle = css({
+  paddingX: 'md',  // 16px horizontal
+  paddingY: 'sm'   // 8px vertical
+});
+```
+
+### Margins
+
+```tsx
+import { css } from 'styled-system/css';
+
+// Section spacing
+const sectionStyle = css({
+  marginBottom: 'xxl'  // 48px bottom margin
+});
+
+// Component gap
+const stackStyle = css({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 'md'  // 16px between children
+});
+```
+
+### Gap (Flexbox/Grid)
+
+```tsx
+import { css } from 'styled-system/css';
+
+// Grid layout
+const gridStyle = css({
+  display: 'grid',
+  gridTemplateColumns: 'repeat(3, 1fr)',
+  gap: 'lg'  // 24px between grid items
+});
+
+// Flex layout
+const flexStyle = css({
+  display: 'flex',
+  gap: 'sm'  // 8px between flex items
+});
+```
+
+---
+
+## Visual Examples
+
+### Compact Layout (sm spacing)
+
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: material3Language.spacing.sm,
+  padding: material3Language.spacing.md,
+  backgroundColor: '#f5f5f5',
+  borderRadius: '8px',
+  marginBottom: '24px'
+}}>
+  <div style={{ padding: '12px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 1 (gap: 8px)
+  </div>
+  <div style={{ padding: '12px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 2
+  </div>
+  <div style={{ padding: '12px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 3
+  </div>
+</div>
+
+### Comfortable Layout (md spacing)
+
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: material3Language.spacing.md,
+  padding: material3Language.spacing.lg,
+  backgroundColor: '#f5f5f5',
+  borderRadius: '8px',
+  marginBottom: '24px'
+}}>
+  <div style={{ padding: '16px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 1 (gap: 16px)
+  </div>
+  <div style={{ padding: '16px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 2
+  </div>
+  <div style={{ padding: '16px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 3
+  </div>
+</div>
+
+### Spacious Layout (lg spacing)
+
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: material3Language.spacing.lg,
+  padding: material3Language.spacing.xl,
+  backgroundColor: '#f5f5f5',
+  borderRadius: '8px'
+}}>
+  <div style={{ padding: '20px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 1 (gap: 24px)
+  </div>
+  <div style={{ padding: '20px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 2
+  </div>
+  <div style={{ padding: '20px', backgroundColor: '#4C662B', color: 'white', borderRadius: '4px' }}>
+    Item 3
+  </div>
+</div>

package/src/stories/foundations/Typography.mdx

@@ -0,0 +1,264 @@
+import { Meta } from '@storybook/blocks';
+import { TypeSpecimen } from './components/TypeSpecimen';
+import { material3Language } from '../../languages/material3.language';
+
+<Meta title="Foundations/Typography" />
+
+# Typography
+
+The Discourser Design System uses Material Design 3's type scale, which provides a comprehensive set of text styles optimized for readability and hierarchy across all screen sizes.
+
+## Font Families
+
+The system uses three font families, each serving a specific purpose:
+
+<div style={{ marginBottom: '32px', padding: '24px', backgroundColor: '#f5f5f5', borderRadius: '8px' }}>
+  <div style={{ marginBottom: '16px' }}>
+    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Display</div>
+    <div style={{ fontFamily: material3Language.typography.fonts.display, fontSize: '24px', marginBottom: '4px' }}>
+      "Fraunces", Georgia, serif
+    </div>
+    <div style={{ fontSize: '12px', color: '#666' }}>
+      Used for display and headline styles. Provides an elegant, editorial feel.
+    </div>
+  </div>
+
+  <div style={{ marginBottom: '16px' }}>
+    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Body</div>
+    <div style={{ fontFamily: material3Language.typography.fonts.body, fontSize: '16px', marginBottom: '4px' }}>
+      "Poppins", -apple-system, BlinkMacSystemFont, sans-serif
+    </div>
+    <div style={{ fontSize: '12px', color: '#666' }}>
+      Used for body text, titles, and labels. Optimized for legibility at all sizes.
+    </div>
+  </div>
+
+  <div>
+    <div style={{ fontWeight: '600', marginBottom: '8px' }}>Monospace</div>
+    <div style={{ fontFamily: material3Language.typography.fonts.mono, fontSize: '14px', marginBottom: '4px' }}>
+      JetBrains Mono, Fira Code, Consolas, monospace
+    </div>
+    <div style={{ fontSize: '12px', color: '#666' }}>
+      Used for code snippets and technical content. Supports ligatures.
+    </div>
+  </div>
+</div>
+
+---
+
+## Type Scale
+
+Material Design 3's type scale consists of 13 styles across 5 categories: Display, Headline, Title, Body, and Label.
+
+### Display Styles
+
+Display styles are the largest text on screen, reserved for short, important text or numerals.
+
+<TypeSpecimen
+  name="Display Large"
+  fontSize={material3Language.typography.scale.displayLarge.fontSize}
+  lineHeight={material3Language.typography.scale.displayLarge.lineHeight}
+  fontWeight={material3Language.typography.scale.displayLarge.fontWeight}
+  letterSpacing={material3Language.typography.scale.displayLarge.letterSpacing}
+  fontFamily={material3Language.typography.scale.displayLarge.fontFamily}
+  sampleText="Display Large"
+/>
+
+<TypeSpecimen
+  name="Display Medium"
+  fontSize={material3Language.typography.scale.displayMedium.fontSize}
+  lineHeight={material3Language.typography.scale.displayMedium.lineHeight}
+  fontWeight={material3Language.typography.scale.displayMedium.fontWeight}
+  letterSpacing={material3Language.typography.scale.displayMedium.letterSpacing}
+  fontFamily={material3Language.typography.scale.displayMedium.fontFamily}
+  sampleText="Display Medium"
+/>
+
+<TypeSpecimen
+  name="Display Small"
+  fontSize={material3Language.typography.scale.displaySmall.fontSize}
+  lineHeight={material3Language.typography.scale.displaySmall.lineHeight}
+  fontWeight={material3Language.typography.scale.displaySmall.fontWeight}
+  letterSpacing={material3Language.typography.scale.displaySmall.letterSpacing}
+  fontFamily={material3Language.typography.scale.displaySmall.fontFamily}
+  sampleText="Display Small"
+/>
+
+### Headline Styles
+
+Headlines are for high-emphasis text on smaller screens. They're best-suited for short, high-emphasis text.
+
+<TypeSpecimen
+  name="Headline Large"
+  fontSize={material3Language.typography.scale.headlineLarge.fontSize}
+  lineHeight={material3Language.typography.scale.headlineLarge.lineHeight}
+  fontWeight={material3Language.typography.scale.headlineLarge.fontWeight}
+  letterSpacing={material3Language.typography.scale.headlineLarge.letterSpacing}
+  fontFamily={material3Language.typography.scale.headlineLarge.fontFamily}
+  sampleText="Headline Large"
+/>
+
+<TypeSpecimen
+  name="Headline Medium"
+  fontSize={material3Language.typography.scale.headlineMedium.fontSize}
+  lineHeight={material3Language.typography.scale.headlineMedium.lineHeight}
+  fontWeight={material3Language.typography.scale.headlineMedium.fontWeight}
+  letterSpacing={material3Language.typography.scale.headlineMedium.letterSpacing}
+  fontFamily={material3Language.typography.scale.headlineMedium.fontFamily}
+  sampleText="Headline Medium"
+/>
+
+<TypeSpecimen
+  name="Headline Small"
+  fontSize={material3Language.typography.scale.headlineSmall.fontSize}
+  lineHeight={material3Language.typography.scale.headlineSmall.lineHeight}
+  fontWeight={material3Language.typography.scale.headlineSmall.fontWeight}
+  letterSpacing={material3Language.typography.scale.headlineSmall.letterSpacing}
+  fontFamily={material3Language.typography.scale.headlineSmall.fontFamily}
+  sampleText="Headline Small"
+/>
+
+### Title Styles
+
+Titles are for medium-emphasis text that remains relatively short. Use titles for grouping related content or to emphasize important sections.
+
+<TypeSpecimen
+  name="Title Large"
+  fontSize={material3Language.typography.scale.titleLarge.fontSize}
+  lineHeight={material3Language.typography.scale.titleLarge.lineHeight}
+  fontWeight={material3Language.typography.scale.titleLarge.fontWeight}
+  letterSpacing={material3Language.typography.scale.titleLarge.letterSpacing}
+  fontFamily={material3Language.typography.scale.titleLarge.fontFamily}
+  sampleText="Title Large"
+/>
+
+<TypeSpecimen
+  name="Title Medium"
+  fontSize={material3Language.typography.scale.titleMedium.fontSize}
+  lineHeight={material3Language.typography.scale.titleMedium.lineHeight}
+  fontWeight={material3Language.typography.scale.titleMedium.fontWeight}
+  letterSpacing={material3Language.typography.scale.titleMedium.letterSpacing}
+  fontFamily={material3Language.typography.scale.titleMedium.fontFamily}
+  sampleText="Title Medium"
+/>
+
+<TypeSpecimen
+  name="Title Small"
+  fontSize={material3Language.typography.scale.titleSmall.fontSize}
+  lineHeight={material3Language.typography.scale.titleSmall.lineHeight}
+  fontWeight={material3Language.typography.scale.titleSmall.fontWeight}
+  letterSpacing={material3Language.typography.scale.titleSmall.letterSpacing}
+  fontFamily={material3Language.typography.scale.titleSmall.fontFamily}
+  sampleText="Title Small"
+/>
+
+### Body Styles
+
+Body styles are used for longer passages of text in your app.
+
+<TypeSpecimen
+  name="Body Large"
+  fontSize={material3Language.typography.scale.bodyLarge.fontSize}
+  lineHeight={material3Language.typography.scale.bodyLarge.lineHeight}
+  fontWeight={material3Language.typography.scale.bodyLarge.fontWeight}
+  letterSpacing={material3Language.typography.scale.bodyLarge.letterSpacing}
+  fontFamily={material3Language.typography.scale.bodyLarge.fontFamily}
+  sampleText="The quick brown fox jumps over the lazy dog. Body Large is used for longer passages of text that require good readability."
+/>
+
+<TypeSpecimen
+  name="Body Medium"
+  fontSize={material3Language.typography.scale.bodyMedium.fontSize}
+  lineHeight={material3Language.typography.scale.bodyMedium.lineHeight}
+  fontWeight={material3Language.typography.scale.bodyMedium.fontWeight}
+  letterSpacing={material3Language.typography.scale.bodyMedium.letterSpacing}
+  fontFamily={material3Language.typography.scale.bodyMedium.fontFamily}
+  sampleText="The quick brown fox jumps over the lazy dog. Body Medium is the default body text size, balanced for readability and screen real estate."
+/>
+
+<TypeSpecimen
+  name="Body Small"
+  fontSize={material3Language.typography.scale.bodySmall.fontSize}
+  lineHeight={material3Language.typography.scale.bodySmall.lineHeight}
+  fontWeight={material3Language.typography.scale.bodySmall.fontWeight}
+  letterSpacing={material3Language.typography.scale.bodySmall.letterSpacing}
+  fontFamily={material3Language.typography.scale.bodySmall.fontFamily}
+  sampleText="The quick brown fox jumps over the lazy dog. Body Small is used for captions and supporting text that doesn't require much emphasis."
+/>
+
+### Label Styles
+
+Label styles are for text in components like buttons, tabs, and labels. They're utilitarian and medium-emphasis.
+
+<TypeSpecimen
+  name="Label Large"
+  fontSize={material3Language.typography.scale.labelLarge.fontSize}
+  lineHeight={material3Language.typography.scale.labelLarge.lineHeight}
+  fontWeight={material3Language.typography.scale.labelLarge.fontWeight}
+  letterSpacing={material3Language.typography.scale.labelLarge.letterSpacing}
+  fontFamily={material3Language.typography.scale.labelLarge.fontFamily}
+  sampleText="Label Large"
+/>
+
+<TypeSpecimen
+  name="Label Medium"
+  fontSize={material3Language.typography.scale.labelMedium.fontSize}
+  lineHeight={material3Language.typography.scale.labelMedium.lineHeight}
+  fontWeight={material3Language.typography.scale.labelMedium.fontWeight}
+  letterSpacing={material3Language.typography.scale.labelMedium.letterSpacing}
+  fontFamily={material3Language.typography.scale.labelMedium.fontFamily}
+  sampleText="Label Medium"
+/>
+
+<TypeSpecimen
+  name="Label Small"
+  fontSize={material3Language.typography.scale.labelSmall.fontSize}
+  lineHeight={material3Language.typography.scale.labelSmall.lineHeight}
+  fontWeight={material3Language.typography.scale.labelSmall.fontWeight}
+  letterSpacing={material3Language.typography.scale.labelSmall.letterSpacing}
+  fontFamily={material3Language.typography.scale.labelSmall.fontFamily}
+  sampleText="Label Small"
+/>
+
+---
+
+## Usage Guidelines
+
+### Choosing the Right Style
+
+**Display**: Hero text, marketing headlines, featured numbers
+**Headline**: Page titles, section headers, card titles
+**Title**: List item titles, dialog titles, form section headers
+**Body**: Paragraphs, descriptions, long-form content
+**Label**: Buttons, tabs, chips, form labels, captions
+
+### Responsive Typography
+
+Consider using different type styles at different breakpoints:
+
+- **Mobile**: Prefer smaller display/headline sizes
+- **Tablet**: Use medium sizes for most content
+- **Desktop**: Larger displays can accommodate bigger type
+
+### Accessibility
+
+- Maintain minimum 16px font size for body text
+- Ensure sufficient line height (1.5 for body text)
+- Use proper heading hierarchy (h1 → h2 → h3)
+- Test with browser zoom up to 200%
+
+### Example Usage
+
+```tsx
+import { css } from 'styled-system/css';
+
+const headingStyle = css({
+  textStyle: 'headlineLarge',
+  color: 'onSurface'
+});
+
+const bodyStyle = css({
+  textStyle: 'bodyMedium',
+  color: 'onSurfaceVariant'
+});
+```

package/src/stories/foundations/components/ColorSwatch.tsx

@@ -0,0 +1,166 @@
+import { type CSSProperties } from 'react';
+
+interface ColorSwatchProps {
+  name: string;
+  value: string;
+  description?: string;
+}
+
+export const ColorSwatch = ({ name, value, description }: ColorSwatchProps) => {
+  const swatchStyle: CSSProperties = {
+    backgroundColor: value,
+    width: '100%',
+    height: '80px',
+    borderRadius: '8px',
+    border: '1px solid rgba(0, 0, 0, 0.1)',
+    marginBottom: '8px',
+  };
+
+  const containerStyle: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    marginBottom: '16px',
+  };
+
+  const labelStyle: CSSProperties = {
+    fontSize: '14px',
+    fontWeight: '500',
+    marginBottom: '4px',
+    fontFamily: 'Inter, sans-serif',
+  };
+
+  const valueStyle: CSSProperties = {
+    fontSize: '12px',
+    fontFamily: 'monospace',
+    color: '#666',
+  };
+
+  const descStyle: CSSProperties = {
+    fontSize: '12px',
+    color: '#666',
+    marginTop: '4px',
+  };
+
+  return (
+    <div style={containerStyle}>
+      <div style={swatchStyle} />
+      <div style={labelStyle}>{name}</div>
+      <div style={valueStyle}>{value}</div>
+      {description && <div style={descStyle}>{description}</div>}
+    </div>
+  );
+};
+
+interface TonalSwatchProps {
+  paletteName: string;
+  tone: number;
+  value: string;
+}
+
+export const TonalSwatch = ({ paletteName, tone, value }: TonalSwatchProps) => {
+  const swatchStyle: CSSProperties = {
+    backgroundColor: value,
+    width: '100%',
+    height: '60px',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    border: '1px solid rgba(0, 0, 0, 0.1)',
+    position: 'relative',
+  };
+
+  const labelStyle: CSSProperties = {
+    fontSize: '11px',
+    fontWeight: '500',
+    fontFamily: 'monospace',
+    color: tone >= 50 ? '#000' : '#fff',
+    mixBlendMode: 'difference',
+  };
+
+  return (
+    <div style={swatchStyle} title={`${paletteName}.${tone}: ${value}`}>
+      <span style={labelStyle}>{tone}</span>
+    </div>
+  );
+};
+
+interface SemanticSwatchProps {
+  name: string;
+  lightValue: string;
+  darkValue: string;
+  description?: string;
+}
+
+export const SemanticSwatch = ({
+  name,
+  lightValue,
+  darkValue,
+  description,
+}: SemanticSwatchProps) => {
+  const containerStyle: CSSProperties = {
+    display: 'grid',
+    gridTemplateColumns: '1fr 1fr',
+    gap: '8px',
+    marginBottom: '16px',
+  };
+
+  const swatchContainerStyle: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+  };
+
+  const swatchStyle = (color: string): CSSProperties => ({
+    backgroundColor: color,
+    height: '80px',
+    borderRadius: '8px',
+    border: '1px solid rgba(0, 0, 0, 0.1)',
+    marginBottom: '8px',
+  });
+
+  const labelStyle: CSSProperties = {
+    fontSize: '14px',
+    fontWeight: '500',
+    marginBottom: '4px',
+    fontFamily: 'Inter, sans-serif',
+  };
+
+  const valueStyle: CSSProperties = {
+    fontSize: '11px',
+    fontFamily: 'monospace',
+    color: '#666',
+  };
+
+  const modeStyle: CSSProperties = {
+    fontSize: '10px',
+    textTransform: 'uppercase',
+    color: '#999',
+    marginBottom: '4px',
+    fontWeight: '600',
+  };
+
+  const descStyle: CSSProperties = {
+    fontSize: '12px',
+    color: '#666',
+    marginTop: '8px',
+    gridColumn: '1 / -1',
+  };
+
+  return (
+    <div>
+      <div style={labelStyle}>{name}</div>
+      <div style={containerStyle}>
+        <div style={swatchContainerStyle}>
+          <div style={modeStyle}>Light</div>
+          <div style={swatchStyle(lightValue)} />
+          <div style={valueStyle}>{lightValue}</div>
+        </div>
+        <div style={swatchContainerStyle}>
+          <div style={modeStyle}>Dark</div>
+          <div style={swatchStyle(darkValue)} />
+          <div style={valueStyle}>{darkValue}</div>
+        </div>
+      </div>
+      {description && <div style={descStyle}>{description}</div>}
+    </div>
+  );
+};