Contributing

Philosophy

Before contributing, understand the principles that guide Canon:

Getting Started

1. Clone the Repository

git clone https://github.com/createsomethingtoday/create-something-monorepo.git
cd create-something-monorepo
pnpm install

2. Run the Dev Server

pnpm dev --filter=components

3. Run Type Checks

pnpm --filter=components check

Adding a Component

1. Check if it exists — Search existing components. Don't duplicate.
2. Question necessity — Does this component earn its existence? Can a pattern or composition of existing components work instead?
3. Create the component — Follow the file structure below.
4. Document it — Add a documentation page in /canon/components/.
5. Export it — Add to the appropriate index.ts.

File Structure

packages/components/src/lib/components/
├── Button/
│   ├── Button.svelte      # Component file
│   └── index.ts           # Re-export
├── TextField/
│   ├── TextField.svelte
│   └── index.ts
└── index.ts               # Package exports

Component Template

<script lang="ts">
  /**
   * ComponentName
   *
   * Brief description of what this component does.
   *
   * Canon Principle: Which principle does this embody?
   */

  interface Props {
    /** Prop description */
    label: string;
    /** Optional prop */
    variant?: 'primary' | 'secondary';
  }

  let {
    label,
    variant = 'primary'
  }: Props = $props();
</script>

<element class="component component--{variant}">
  {label}
</element>

<style>
  .component {
    /* Use Canon tokens */
    padding: var(--space-sm);
    color: var(--color-fg-primary);
  }
</style>

Modifying Tokens

Tokens are the foundation. Changes cascade everywhere.

Token Source

Edit tokens in:

packages/components/src/lib/styles/tokens.css

Regenerate Exports

After editing tokens, regenerate derived formats:

pnpm --filter=components tokens:export

This generates:

• tokens.scss — SCSS variables
• tokens.dtcg.json — W3C Design Token format
• tokens.figma.json — Tokens Studio format
• canon.json — Structured JSON

Code Standards

TypeScript

• All components use TypeScript
• Define explicit Props interface
• Document props with JSDoc comments
• Use Svelte 5 runes ($props, $state, $derived)

CSS

• Use Canon tokens for all values (colors, spacing, typography)
• No hardcoded colors or pixel values
• Tailwind for structure, Canon for aesthetics
• Include :focus-visible styles for interactives

Accessibility

• WCAG 2.1 AA compliance required
• Keyboard navigation must work
• Screen reader tested
• Include prefers-reduced-motion support

Commit Messages

Follow conventional commits format:

feat(components): add Tooltip component
fix(tokens): correct spacing token values
docs(canon): add Button documentation
refactor(components): simplify Card props

Pull Request Process

1. Create a branch from main
2. Make changes following the guidelines above
3. Run checks — pnpm check and pnpm build
4. Create PR with clear description
5. Address feedback from review

PR Checklist