Ribble UI

A modern, framework-agnostic UI component library and design system for building beautiful, accessible, and consistent user interfaces across web applications.

---

📚 Table of Contents

• Features
• Quick Start
• Monorepo Structure
• Example: Using a Button
• Design Tokens
• Contributing
• Documentation
• Community
• FAQ
• Vision

---

✨ Features

• Web Components: Core UI elements built as standard Web Components in TypeScript
• Framework Adapters: First-class support for React, Vue, Svelte, and Angular
• Design Tokens: Centralized, themeable tokens for color, typography, spacing, and more
• Theming: Light/dark mode, brand customization, and responsive design out of the box
• CLI Tools: Automate scaffolding, building, and documentation
• Type Safety: Fully typed APIs and tokens for robust development
• Accessible by Design: ARIA, keyboard navigation, and focus management baked in
• Monorepo: Managed with pnpm workspaces for easy development and contribution

---

🚀 Quick Start

1. Install dependencies:

   pnpm install

2. Start the development server (core package):

   pnpm dev

3. Explore the playground:

   pnpm --filter @ribble-ui/playground dev

Framework-specific Usage

React

pnpm add @ribble-ui/react

import { Button } from '@ribble-ui/react';
<Button>Click me!</Button>;

Vue

pnpm add @ribble-ui/vue

<template>
  <Button>Click me!</Button>
</template>
<script setup>
import { Button } from '@ribble-ui/vue';
</script>

Svelte

pnpm add @ribble-ui/svelte

<script>
  import { Button } from '@ribble-ui/svelte';
</script>
<Button>Click me!</Button>

Angular

pnpm add @ribble-ui/angular

import { MyButton } from '@ribble-ui/angular';
// ... use <my-button label="Click me!"></my-button> in templates

---

📦 Monorepo Structure

• packages/core – Web Components & design tokens
• packages/react – React adapter
• packages/vue – Vue adapter
• packages/svelte – Svelte adapter
• packages/angular – Angular adapter
• packages/cli – CLI tool
• docs – Documentation site (Storybook, guides)
• packages/configs – Shared configs
• packages/testing – Testing utilities

---

🧩 Usage Examples

import { MyButton } from '@ribble-ui/core';

<MyButton label="Click me!" />;

Or with React:

import { Button } from '@ribble-ui/react';

<Button>Click me!</Button>;

---

🎨 Design Tokens

• Color: Light/dark, semantic, and brand palettes
• Typography: Fluid, responsive font scales
• Spacing: Modular, consistent spacing system
• Radius, Shadow, Animation, Breakpoints, Z-Index: All customizable and type-safe

---

🛠️ Contributing

We welcome contributions! Note: A CONTRIBUTING.md should be created for detailed guidelines.

• Fork and clone the repo
• Create a new branch for your feature or fix
• Run tests and build locally
• Submit a pull request

Please follow our code style and commit conventions. If you have questions, open an issue or discussion.

---

📖 Documentation

• See the docs/ directory for guides, usage, and Storybook
• Each package contains its own README for details

🌐 Community

• GitHub Issues — Bug reports & feature requests
• Discussions — Q&A, ideas, and feedback
• Discord — Chat with the team and community

---

❓ FAQ

Q: Is Ribble UI production-ready? A: Yes, but we recommend testing in your environment before deploying at scale.

Q: Can I use Ribble UI with other frameworks? A: Yes! Core components are Web Components, so you can use them anywhere.

Q: How do I customize themes? A: See the docs/design-tokens/usage.md for theming instructions.

---

🏆 Vision

Ribble UI aims to be the most flexible, accessible, and modern UI toolkit for web apps—empowering teams to build consistent, beautiful products at scale.

Roadmap: See GitHub Projects for upcoming features and plans.

---

© 2024 Ribble UI. MIT License.