🤖 LLM/Codegen Design System Best Practices

📋 Overview

This guide provides comprehensive best practices for any LLM/Codegen tool building design systems with Storybook. These standards ensure consistency, quality, and maintainability across all automated development processes.

🏗️ Universal Development Standards

Required File Structure

src/components/ComponentName/
├── ComponentName.tsx          # Main component (REQUIRED)
├── ComponentName.stories.tsx  # Storybook stories (REQUIRED)
├── ComponentName.test.tsx     # Unit tests (REQUIRED)
├── ComponentName.types.ts     # Type definitions (OPTIONAL)
├── ComponentName.utils.ts     # Helper functions (OPTIONAL)
└── index.ts                   # Clean exports (REQUIRED)

Naming Conventions

Components: PascalCase (Button, ActivityCard)
Files: PascalCase (Button.tsx, Button.stories.tsx)
Stories: PascalCase (Button.stories.tsx)
Types: PascalCase with Props suffix (ButtonProps)

📖 Storybook Standards for LLM/Codegen

Required Story Structure

Every component MUST include these story types:

// REQUIRED: Default story
export const Default: Story = {
  args: {
    // Basic props
  },
};

// REQUIRED: Variants story
export const Variants: Story = {
  render: () => (
    <div className="flex gap-4">
      <Component variant="primary" />
      <Component variant="secondary" />
      <Component variant="outline" />
    </div>
  ),
};

// REQUIRED: Sizes story
export const Sizes: Story = {
  render: () => (
    <div className="flex items-center gap-4">
      <Component size="sm" />
      <Component size="md" />
      <Component size="lg" />
    </div>
  ),
};

// REQUIRED: States story
export const States: Story = {
  render: () => (
    <div className="flex gap-4">
      <Component />
      <Component disabled />
      <Component loading />
    </div>
  ),
};

// REQUIRED: Accessibility story
export const Accessibility: Story = {
  render: () => (
    <div>
      <Component aria-label="Submit form" />
      <Component aria-describedby="help-text" />
    </div>
  ),
  parameters: {
    a11y: {
      config: {
        rules: [
          { id: 'button-name', enabled: true },
          { id: 'color-contrast', enabled: true },
        ],
      },
    },
  },
};

Required Story Metadata

const meta: Meta<typeof Component> = {
  title: 'Design System/ComponentName', // REQUIRED: Use this format
  component: Component,
  parameters: {
    layout: 'centered',
    docs: {
      description: {
        component: `
# ComponentName Component

Brief description of the component.

## Usage

\`\`\`tsx
import { ComponentName } from '@juniro/design-system';

<ComponentName variant="primary" size="md">
  Content
</ComponentName>
\`\`\`

## Accessibility

- Keyboard navigation support
- Screen reader compatible
- ARIA attributes included
        `,
      },
    },
  },
  argTypes: {
    // REQUIRED: Document all props
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline'],
      description: 'The visual style variant',
      table: {
        type: { summary: 'string' },
        defaultValue: { summary: 'primary' },
      },
    },
  },
  tags: ['autodocs', 'design-system'], // REQUIRED tags
};

🧪 Testing Standards for Automated Development

Required Test Coverage

Every component MUST include:

// REQUIRED: Basic rendering test
it('renders correctly', () => {
  render(<Component>Test</Component>);
  expect(screen.getByText('Test')).toBeInTheDocument();
});

// REQUIRED: Props testing
it('applies variant classes correctly', () => {
  render(<Component variant="primary" />);
  expect(screen.getByRole('button')).toHaveClass('bg-blue-600');
});

// REQUIRED: Event handling test
it('handles click events', () => {
  const handleClick = jest.fn();
  render(<Component onClick={handleClick} />);
  fireEvent.click(screen.getByRole('button'));
  expect(handleClick).toHaveBeenCalledTimes(1);
});

// REQUIRED: Accessibility test
it('has proper accessibility attributes', () => {
  render(<Component aria-label="Test button" />);
  expect(screen.getByLabelText('Test button')).toBeInTheDocument();
});

♿ Accessibility Standards

Required Accessibility Features

Keyboard Navigation: All interactive elements must be keyboard accessible
Screen Reader Support: Proper ARIA attributes and semantic HTML
Focus Management: Visible focus indicators
Color Contrast: Meet WCAG 2.1 AA standards (4.5:1 ratio)

Required ARIA Attributes

// REQUIRED: Basic accessibility
<button
  aria-label="Submit form"
  aria-describedby="help-text"
  aria-pressed="false"
  role="button"
>
  Submit
</button>

⚡ Performance Standards

Bundle Size Limits

Individual Component: < 5KB gzipped
Total Design System: < 50KB gzipped
Story Load Time: < 2 seconds

Performance Testing

// REQUIRED: Performance story
export const Performance: Story = {
  render: () => (
    <div className="grid grid-cols-10 gap-2">
      {Array.from({ length: 100 }).map((_, i) => (
        <Component key={i} size="sm">
          {i}
        </Component>
      ))}
    </div>
  ),
  parameters: {
    chromatic: { delay: 1000 },
  },
};

🎯 Component Development Checklist

Before Creating a Component

Check if similar component exists
Review design tokens for consistency
Plan accessibility requirements
Consider performance implications

During Development

Follow TypeScript strict mode
Use design tokens (colors, spacing, typography)
Implement all required variants
Add comprehensive prop interfaces
Include accessibility attributes

Before Committing

📚 Documentation Standards

Required Documentation

Component API: All props documented with types and examples
Usage Examples: Real-world usage scenarios
Accessibility Guidelines: How to use with screen readers
Performance Notes: Any performance considerations

Code Comments

/**
 * Button component with multiple variants and states
 * 
 * @example
 * ```tsx
 * <Button variant="primary" size="md" onClick={handleClick}>
 *   Click me
 * </Button>
 * ```
 */
export interface ButtonProps {
  /** The visual style variant of the button */
  variant?: 'primary' | 'secondary' | 'outline';
  
  /** The size of the button */
  size?: 'sm' | 'md' | 'lg';
}

🔧 Development Workflow

1. Component Creation Process

# 1. Create component directory
mkdir src/components/shared/NewComponent

# 2. Create component files
touch src/components/shared/NewComponent/NewComponent.tsx
touch src/components/shared/NewComponent/NewComponent.stories.tsx
touch src/components/shared/NewComponent/NewComponent.test.tsx
touch src/components/shared/NewComponent/index.ts

# 3. Update shared index
# Add export to src/components/shared/index.ts

# 4. Test locally
npm run storybook
npm run test

2. Quality Gates

Before merging any component:

🚨 Common Mistakes to Avoid

❌ Don't Do This

// ❌ Inconsistent naming
export const MyCustomButton = () => {};

// ❌ Missing accessibility
<button onClick={handleClick}>Click</button>

// ❌ No error handling
const Component = ({ data }) => <div>{data.property}</div>;

// ❌ Hardcoded values
<div className="bg-blue-500 p-4">Content</div>

✅ Do This Instead

// ✅ Consistent naming
export const Button = () => {};

// ✅ Proper accessibility
<button 
  onClick={handleClick}
  aria-label="Submit form"
  role="button"
>
  Click
</button>

// ✅ Error handling
const Component = ({ data }) => (
  <div>{data?.property || 'Default'}</div>
);

// ✅ Use design tokens
<div className="bg-primary-500 p-4">Content</div>

🤖 LLM/Codegen Specific Guidelines

1. Consistent Code Generation

Always follow the established patterns
Use the component template as a base
Generate all required files (component, stories, tests, index)
Include comprehensive TypeScript interfaces

2. Quality Assurance

Run automated tests after generation
Validate accessibility compliance
Check bundle size impact
Verify Storybook integration

3. Documentation Generation

Generate comprehensive JSDoc comments
Include usage examples
Document accessibility features
Add performance considerations

4. Error Handling

Validate input parameters
Provide meaningful error messages
Include fallback states
Handle edge cases gracefully

📊 Success Metrics

Quality Metrics

Test Coverage: Target 90%+
Accessibility Score: Target 100% (WCAG 2.1 AA)
Bundle Size: Target less than 50KB gzipped
Performance: Target under 3s load time

Development Metrics

Component Consistency: All components follow same patterns
Documentation Completeness: 100% of components documented
Build Success Rate: 100% successful builds
Test Pass Rate: 100% test pass rate

🔄 Continuous Improvement

Automated Validation

Implement CI/CD pipelines
Add automated accessibility testing
Include performance monitoring
Set up visual regression testing

Quality Monitoring

Track component usage patterns
Monitor performance metrics
Collect accessibility feedback
Measure developer satisfaction

Remember: These standards ensure that any LLM/Codegen tool can produce consistent, high-quality design system components that meet enterprise-grade requirements for accessibility, performance, and maintainability.

📋 Overview​

🏗️ Universal Development Standards​

Required File Structure​

Naming Conventions​

📖 Storybook Standards for LLM/Codegen​

Required Story Structure​

Required Story Metadata​

🧪 Testing Standards for Automated Development​

Required Test Coverage​

♿ Accessibility Standards​

Required Accessibility Features​

Required ARIA Attributes​

⚡ Performance Standards​

Bundle Size Limits​

Performance Testing​

🎯 Component Development Checklist​

Before Creating a Component​

During Development​

Before Committing​

📚 Documentation Standards​

Required Documentation​

Code Comments​

🔧 Development Workflow​

1. Component Creation Process​

2. Quality Gates​

🚨 Common Mistakes to Avoid​

❌ Don't Do This​

✅ Do This Instead​

🤖 LLM/Codegen Specific Guidelines​

1. Consistent Code Generation​

2. Quality Assurance​

3. Documentation Generation​

4. Error Handling​

📊 Success Metrics​

Quality Metrics​

Development Metrics​

🔄 Continuous Improvement​

Automated Validation​

Quality Monitoring​