diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 00000000..2cab465a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Device:**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 00000000..786b4944
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: 'feature request'
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000..02ad4b2c
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,3 @@
+## Summary
+
+## Test Plan
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..f73178f7
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-01-23
+
+### Initialized components library
+
+| Component | Description |
+|-----------|-------------|
+| `Accordion` | Expandable content sections |
+| `Badge` | Status and label badges |
+| `Callout` | Highlighted information boxes |
+| `Card` | Content cards |
+| `CodeBlock` | Syntax-highlighted code with copy button |
+| `CodeGroup` | Code blocks container with tabs or dropdown selection |
+| `Columns` | Multi-column layouts |
+| `Expandable` | Collapsible sections |
+| `Frame` | Image and content frames |
+| `Icon` | Icon rendering |
+| `Mermaid` | Diagram rendering |
+| `Panel` | Panel layouts |
+| `Property` | API property display |
+| `Steps` | Step-by-step instructions |
+| `Tabs` | Tabbed interfaces |
+| `Tile` | Tile grids |
+| `Tooltip` | Hover tooltips |
+| `Tree` | Hierarchical tree views |
+| `Update` | Changelog entries |
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..a6b5556b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,79 @@
+# Contributing to Mintlify Components
+
+Thank you for your interest in contributing to Mintlify Components! This document provides guidelines and information for contributors.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork locally
+3. Follow the setup instructions in [DEVELOPMENT.md](./DEVELOPMENT.md)
+
+## Issue Labels
+
+We use three labels to categorize issues:
+
+- **bug** - Something isn't working as expected
+- **improvement** - Enhancement to an existing component
+- **feature request** - Request for a new component or capability
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Check the [existing issues](https://github.com/mintlify/components/issues) to avoid duplicates
+- [Open a bug report](https://github.com/mintlify/components/issues/new?template=bug_report.md) using the template
+- Include reproduction steps, expected behavior, and actual behavior
+- Add screenshots or code snippets if helpful
+
+### Requesting Features or Improvements
+
+- Check existing issues first to avoid duplicates
+- [Open a feature request](https://github.com/mintlify/components/issues/new?template=feature_request.md) using the template
+- For improvements to existing components, add the `improvement` label
+- Describe the use case and why it would be valuable
+
+### Submitting Changes
+
+1. Create a new branch from `main`
+2. Make your changes following our code style guidelines
+3. Add or update tests and Storybook stories as needed
+4. Run `pnpm lint:check` to ensure code quality
+5. Run `pnpm build` to verify the build succeeds
+6. Submit a pull request
+
+### Pull Request Guidelines
+
+When you open a PR, you'll see a template with sections for Summary and Test Plan. Please fill these out.
+
+- Keep PRs focused on a single change
+- Write clear commit messages
+- Update documentation if needed
+- Ensure all CI checks pass
+
+## Code Style
+
+- Use TypeScript for all code
+- Follow existing patterns in the codebase
+- Use Tailwind CSS for styling
+- Run `pnpm lint:fix` to auto-format code
+
+## Component Guidelines
+
+When adding or modifying components:
+
+- Ensure compatibility with React 18 and 19
+- Support both light and dark themes
+- Make components accessible (ARIA attributes, keyboard navigation)
+- Add Storybook stories documenting usage
+- Export types for TypeScript users
+
+## Questions?
+
+If you have questions, feel free to:
+
+- Open a [GitHub Discussion](https://github.com/mintlify/components/discussions)
+- Check our [documentation](https://www.mintlify.com/docs/components)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 00000000..d8e3bfbf
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,106 @@
+# Development Guide
+
+This guide covers how to set up and work on Mintlify Components locally.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 20.0.0
+- [pnpm](https://pnpm.io/) >= 10.0.0
+
+## Getting Started
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/mintlify/components.git
+cd components
+```
+
+2. Install dependencies:
+
+```bash
+pnpm install
+```
+
+3. Set up pre-commit hooks:
+
+```bash
+pnpm exec husky install
+```
+
+## Development Workflow
+
+### Building
+
+Build the component library:
+
+```bash
+pnpm build
+```
+
+For development with watch mode:
+
+```bash
+pnpm dev
+```
+
+### Storybook
+
+Run Storybook to develop and preview components:
+
+```bash
+pnpm storybook
+```
+
+This starts a local server at `http://localhost:6006` where you can view and interact with all components.
+
+Build Storybook for production:
+
+```bash
+pnpm build-storybook
+```
+
+### Linting
+
+Check code style:
+
+```bash
+pnpm lint:check
+```
+
+Fix linting issues automatically:
+
+```bash
+pnpm lint:fix
+```
+
+We use [Biome](https://biomejs.dev/) for linting and formatting. The pre-commit hooks will run linting automatically before each commit.
+
+## Project Structure
+
+```
+packages/
+└── components/ # Main component package
+ ├── src/
+ │ ├── components/ # React components
+ │ ├── hooks/ # Custom React hooks
+ │ ├── utils/ # Utility functions
+ │ └── index.ts # Package entry point
+ ├── .storybook/ # Storybook configuration
+ └── dist/ # Build output
+```
+
+## Adding a New Component
+
+1. Create a new directory under `packages/components/src/components/`
+2. Implement the component with TypeScript
+3. Export it from `packages/components/src/components/index.ts`
+4. Add a Storybook story for documentation
+5. Run `pnpm build` to verify the build succeeds
+
+## Code Style
+
+- Use TypeScript for all new code
+- Follow existing patterns in the codebase
+- Components should be compatible with React 18 and 19
+- Use Tailwind CSS for styling
diff --git a/README.md b/README.md
index 7afcfeee..2a3f9617 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,63 @@
# Mintlify Components
-Mintlify's Open Source UI components
+Open source React UI components for documentation sites, built with Tailwind CSS.
+
+[](https://www.npmjs.com/package/@mintlify/components)
+[](https://opensource.org/licenses/MIT)
## Installation
```bash
-pnpm install
+npm install @mintlify/components
+# or
+pnpm add @mintlify/components
+# or
+yarn add @mintlify/components
```
-## Development
+## Requirements
-```bash
-pnpm build
+- Node.js >= 20.0.0
+- React ^18.0.0 or ^19.0.0
+
+## Usage
+
+Import components and styles in your project:
+
+```tsx
+import { Accordion, Callout, CodeBlock, Tabs } from '@mintlify/components';
+import '@mintlify/components/styles.css';
```
-Set up the husky pre-commit hooks or run `pnpm lint` before committing
+### Example
-## Storybook
+```tsx
+import { Callout } from '@mintlify/components';
+import '@mintlify/components/styles.css';
-```bash
-pnpm storybook
+function App() {
+ return (
+
+ This is an informational callout.
+
+ );
+}
```
+## Components
+
+
+## Documentation
+
+- [Component Documentation](https://www.mintlify.com/docs/components)
+- [Storybook Examples](https://storybook.mintlify.com)
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+For local development setup, see [Development](./DEVELOPMENT.md).
+
## License
-MIT
+MIT License - see [LICENSE](./LICENSE) for details.
diff --git a/agents/Rules.md b/agents/Rules.md
deleted file mode 100644
index 88c9a907..00000000
--- a/agents/Rules.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Docs Components rules & audit
-
-
-
-## General rules:
-
-- all components must support `className` on the root element
-- add `data-component-part` attributes on internal sub-elements to allow deep targeting for custom CSS
-- use a single, descriptive word for the root component (`Card, Steps, Property`)
-- sub-components: use dot notation for nested elements (`Steps.Item, Tabs.Item, Colors.Item`) to define scope and avoid global naming conflicts
-- support sub-components outside the parent where it makes sense (if possible and make sense)
-- unify `title, description, cta, href` naming across all components
-- use `icon` for single markers. use `leadIcon` and `tailIcon` for multiple markers
-
----
-
-## What can we add?
-
-- a dedicated section for “Blocks” - copy-pasteable, pre-configured layouts using our components
-
----
-
-## Components refactoring:
-
-
-
-- ~~Accordions~~
- - ~~Rename `` to ``~~
- - ~~Add `data-component-part` **for:~~
- - ~~``~~
-- ~~Badge~~
- - ~~add `tailIcon` + `leadIcon` , current `icon` prop should be `tailIcon`~~
- - ~~rename `stroke` to `variant="outline"`~~
- - ~~add support for the props `onClick` and `href`~~
-- ~~Banner~~
-- ~~Callouts~~
- - ~~update to `variant="note"` instead of 7 different components. add `variant="custom"`, set it by default~~
-- ~~Cards~~
-- ~~Code groups~~
-- ~~Color~~
- - nits https://mintlify.slack.com/archives/C09QQDHD7PG/p1764635576242229?thread_ts=1763963569.715779&cid=C09QQDHD7PG
-- ~~Columns~~
- - i think we should build something more flexible like `Grid, Grid.Row, Grid.Col`
-- ~~Examples~~
- - ~~we can remove this and just use `Panel` + `CodeGroup`~~
-- ~~Expandables~~
- - new name: `Collapsible` or `Accordion`?
-- ~~Fields~~
- - ~~rename to `Property`~~
-- ~~Frames~~
- - ~~`caption` → `description`~~
- - ~~`hint` → `title`~~
-- ~~Icons~~
-- ~~Mermaid~~
-- Panel
-- ~~Steps~~
- - ~~`Step` → `Steps.Item`~~
-- ~~Tabs~~
- - ~~`Tab` → `Tabs.Item`~~
-- Tiles
-- ~~Tooltips~~
- - ~~`headline` → `title`~~
- - ~~`tip` → `description`~~
- - ~~add trigger identification (Classes)~~
-~~- Tree~~
-- Update
-- View
-
----
diff --git a/agents/Web-Interface-Guidelines.md b/agents/Web-Interface-Guidelines.md
deleted file mode 100644
index 0ece6b99..00000000
--- a/agents/Web-Interface-Guidelines.md
+++ /dev/null
@@ -1,149 +0,0 @@
-Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions.
-
-## Interactions
-
-### Keyboard
-
-- MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/)
-- MUST: Visible focus rings (`:focus-visible`; group with `:focus-within`)
-- MUST: Manage focus (trap, move, return) per APG patterns
-- NEVER: `outline: none` without visible focus replacement
-
-### Targets & Input
-
-- MUST: Hit target ≥24px (mobile ≥44px); if visual <24px, expand hit area
-- MUST: Mobile `` font-size ≥16px to prevent iOS zoom
-- NEVER: Disable browser zoom (`user-scalable=no`, `maximum-scale=1`)
-- MUST: `touch-action: manipulation` to prevent double-tap zoom
-- SHOULD: Set `-webkit-tap-highlight-color` to match design
-
-### Forms
-
-- MUST: Hydration-safe inputs (no lost focus/value)
-- NEVER: Block paste in ``/`