Contribution Guide

This guide outlines the process and standards for contributing to the LOKE Design System. Whether you're fixing a bug, improving documentation, or adding a new component, this guide will help you understand how to contribute effectively.

Overview

The LOKE Design System is built and maintained specifically for LOKE applications. Contributions from LOKE team members help ensure the system evolves with our product needs and maintains consistency across our ecosystem.

Getting Started

Repository Setup

1. Clone the repository:

   git clone https://github.com/LOKE/design-system-beta
   cd design-system-beta

2. Install dependencies:

   bun install

3. Start the development environment:

   bun dev

This will launch the documentation site where you can explore components, test your changes, and see live documentation updates.

Development Workflow

Branch Strategy

• main: The production branch containing the latest stable release
• feature/*: Feature branches for new components or significant changes
• fix/*: Branches for bug fixes

Always create a new branch from main when starting work on a new feature or fix:

git checkout main
git pull
git checkout -b feature/your-feature-name

Creating Changesets

We use changesets to manage versioning and changelogs.

Before submitting a PR, create a changeset that describes your changes:

bun changeset

Follow the prompts to:

1. Select the package(s) you've modified
2. Choose the appropriate semver increment (patch, minor, major)
3. Write a description of your changes

This will create a markdown file in the .changeset directory that will be used to generate the changelog when the changes are released.

Code Standards

The repository includes Biome and TypeScript configurations that enforce code standards. Run the linter before submitting your PR:

bun lint

To check TypeScript types:

bun check-types

Component Development Guidelines

When creating or modifying components for LOKE products:

1. Modular Structure: Each component should be in its own directory
2. TypeScript: All components must be written in TypeScript for type safety
3. Documentation: Create comprehensive MDX documentation pages
4. Accessibility: Ensure all components meet WCAG 2.1 AA standards
5. Testing: Include relevant tests for your component
6. Performance: Optimize for real-world LOKE product usage patterns
7. Brand Consistency: Follow LOKE design principles and visual identity

Folder Structure

Components should follow this folder structure:

packages/design-system/src/components/your-component/
├── index.ts             # Exports from the component
├── YourComponent.tsx    # Main component implementation
└── YourComponent.test.tsx  # Component tests (if applicable)

Documentation should be added to the docs site:

apps/docs/src/content/docs/components/
└── your-component.mdx   # Component documentation page

Pull Request Process

1. Create a PR: Push your branch and create a pull request against main
2. CI Checks: Ensure all CI checks pass (linting, type checking, tests)
3. Code Review: Request review from team members
4. Feedback: Address any feedback from reviewers
5. Approval: Once approved, your PR will be merged by a maintainer

Release Process

Releases are managed by the design system maintainers. The process generally follows these steps:

1. Changesets are collected from merged PRs
2. Maintainers run the release workflow which:
   • Updates versions based on changesets
   • Generates changelogs
   • Publishes to the package registry

Adding New Components

When adding a new component:

1. Research: Ensure the component is needed and not duplicating existing functionality
2. Design Review: Get design approval for the component
3. Implementation: Develop the component following our guidelines
4. Documentation: Create comprehensive documentation and stories
5. Testing: Thoroughly test the component, including accessibility tests
6. Example Usage: Include example usage in your PR description

Component Documentation Template

Documentation for each component should include:

• Component purpose and use cases
• Props API documentation
• Examples of basic and advanced usage
• Accessibility considerations
• Any known limitations or caveats

Updating Existing Components

When updating existing components:

1. Backward Compatibility: Consider the impact on existing usage
2. Semver: Follow semantic versioning guidelines
   • Patch: Bug fixes and minor changes that don't affect the API
   • Minor: New features that don't break existing functionality
   • Major: Breaking changes to the component API
3. Migration Guide: For breaking changes, provide a migration guide

Icons

To add new icons to the system:

1. Place the SVG file in the src/icons/svg/{source} directory
2. Run the icon generation script:

   bun build:icons

3. This will generate the React component and update exports

Follow these guidelines for icon SVGs:

• Use a 24×24 viewBox
• Use simple paths with minimal points
• Use a consistent stroke width (typically 2px)
• Remove unnecessary metadata

Styling Guidelines

• Use the built-in theme variables for colors
• Follow the spacing scale for margins and padding
• Use the Tailwind class naming convention

Testing

Components should be tested for:

• Functionality — Core behaviors work as expected
• Accessibility — WCAG 2.1 AA compliance
• Responsive behavior — Works across LOKE product viewport sizes
• Cross-browser compatibility — Tested in browsers used by LOKE customers
• Type safety — TypeScript types are accurate and helpful

To run type checks:

bun check-types

To run linting:

bun lint

Documentation Best Practices

• Use clear, concise language
• Include examples for different use cases
• Document all props with types and descriptions
• Explain any non-obvious behaviors
• Provide accessibility information

Troubleshooting

Common Issues

1. Development server not starting: Try clearing caches and reinstalling dependencies

   rm -rf node_modules .next
   bun install
   bun dev

2. Type errors: Ensure all packages are built and dependencies are up to date

   bun run build
   bun check-types

3. Build errors: Make sure all dependencies are properly installed

   bun install

Getting Help

If you need help contributing to the LOKE Design System:

• Documentation — Check existing documentation and component examples
• Team — Reach out to other LOKE engineers on Slack
• Codebase — Look for similar components or patterns in the repository
• Design Team — Consult with LOKE designers for visual and UX guidance

Conclusion

Thank you for contributing to the LOKE Design System! Your efforts help improve the quality and consistency of all LOKE products.

Remember:

• This system serves LOKE products — design decisions should align with LOKE's product needs
• Quality over speed — take time to ensure accessibility, performance, and maintainability
• Documentation matters — good docs help other LOKE developers use components correctly
• Ask questions — the team is here to help you contribute effectively

The design system is a living project that evolves with LOKE's needs. Your contributions shape the future of our product ecosystem.