Eidetic

Contributing

Docs

How to contribute to Eidetic — from reporting bugs to submitting pull requests.

Report a bug
Submit a PR
Add a component
Write docs

Getting Set Up

Clone the repository and install dependencies to start contributing.

git clone https://github.com/vidorra/eidetic.git
cd eidetic
npm install
npm run dev

The dev server runs on localhost:3000. All documentation pages are in app/docs/ and components live in src/components/.

Reporting Bugs

Found something broken? Open an issue with:

  • A clear title describing the problem
  • Steps to reproduce the bug
  • Expected vs. actual behavior
  • Browser and OS information
  • A screenshot or screen recording if visual

Pull Requests

We follow a standard fork-and-PR workflow.

1
Fork & branch

Create a feature branch from main: feat/your-feature or fix/your-fix.

2
Make your changes

Follow the code style and component rules below.

3
Test

Run npm run test to ensure all tests pass. Add tests for new features.

4
Build check

Run npm run build to verify there are no TypeScript or build errors.

5
Open a PR

Target the main branch. Describe what changed and why.

Component Rules

When creating or modifying components, follow these rules:

UI Components

  • Use Radix UI primitives for accessible behavior
  • Support className pass-through with cn()
  • Use design tokens (CSS custom properties) for colors and spacing
  • Support dark mode via Tailwind dark: variants
  • Use forwardRef for DOM element access

Block Components

  • Always use Eidetic UI components — never native <select>, <input type="checkbox">, etc.
  • Use Button leftIcon/rightIcon props for icons — not inline children
  • Use opacity-0 group-hover:opacity-100 for hover reveals — never hidden group-hover:flex
  • Include BlockHeader for consistent headers

Testing

We use Vitest and Testing Library for component tests.

# Run all tests
npm run test


# Run tests in watch mode
npm run test -- --watch


# Run tests for a specific component
npm run test -- Button

Tests live alongside their components (e.g. Button.test.tsx). Every new component should have tests covering rendering, variants, interactions, and accessibility.

Documentation

Every component needs a documentation page in app/docs/components/. Doc pages should include:

  • Interactive demos with live examples
  • Props table with types and defaults
  • Variant showcase
  • Accessibility notes
  • Related components

Use the shared doc components: DocHeader, DocSection, CodeBlock, PropsTable, and AccessibilityNotes.

CLI Distribution

Eidetic uses a shadcn-style CLI for component distribution. When adding new components, register them in components.json so they can be installed via:

npx @vidorra/eidetic add <component-name>