betty-design-system

v1.0.1

Published

6 months ago

A modern, production-ready React component library with zero-runtime CSS and comprehensive theming

Downloads

0High
0Medium
0Low

react design-system components typescript theme design-tokens storybook css-variables zero-runtime nextjs accessible wcag

betty-design-system

A production-ready, accessible React component library built with TypeScript.

📦 Installation

npm install betty-design-system
# or
yarn add betty-design-system
# or
pnpm add betty-design-system

🚀 Quick Start

⚠️ Important: Import CSS Styles

The design system requires you to import the CSS file in your app's entry point:

// main.tsx or App.tsx
import 'betty-design-system/styles.css'; // ← Required!
import { Button, TextField } from 'betty-design-system';

function App() {
  return (
    <form>
      <TextField
        label="Email"
        type="email"
        required
      />
      <Button variant="contained" color="primary">
        Submit
      </Button>
    </form>
  );
}

Setup Examples

Vite

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import 'betty-design-system/styles.css'; // ← Import first
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Next.js (App Router)

// app/layout.tsx
import 'betty-design-system/styles.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Next.js (Pages Router)

// pages/_app.tsx
import 'betty-design-system/styles.css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

📚 Available Components

Betty Design System currently includes:

| Component | Description | Status | |-----------|-------------|--------| | Button | Full-featured button with variants, colors, sizes | ✅ Stable | | TextField | Versatile input with single-line and multiline support | ✅ Stable | | InputBase | Low-level input foundation (for custom variants) | ✅ Stable | | OutlinedInput | Input with outlined border style | ✅ Stable | | FilledInput | Input with filled background style | ✅ Stable |

Public API Components

Use these components in your application:

✅ Button - Primary action button
✅ TextField - Text input with label and helper text

Advanced/Internal Components

For custom variants and advanced use cases:

InputBase - Build custom input variants
OutlinedInput - Pre-styled outlined variant
FilledInput - Pre-styled filled variant

📖 Component Documentation

Button

Full-featured button with variants, colors, and sizes.

import { Button } from 'betty-design-system';

// Variants
<Button variant="contained">Contained</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="text">Text</Button>

// Colors
<Button color="primary">Primary</Button>
<Button color="secondary">Secondary</Button>
<Button color="error">Error</Button>
<Button color="success">Success</Button>

// Sizes
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>

// States
<Button disabled>Disabled</Button>
<Button fullWidth>Full Width</Button>

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | variant | 'contained' \| 'outlined' \| 'text' | 'contained' | Visual style | | color | 'primary' \| 'secondary' \| 'error' \| 'success' | 'primary' | Color theme | | size | 'small' \| 'medium' \| 'large' | 'medium' | Button size | | disabled | boolean | false | Disable button | | fullWidth | boolean | false | Full width | | onClick | (e: MouseEvent) => void | - | Click handler |

TextField

Versatile input component supporting single-line and multiline text.

import { TextField } from 'betty-design-system';

// Basic input
<TextField label="Name" />

// With validation
<TextField
  label="Email"
  type="email"
  error
  helperText="Invalid email format"
/>

// Multiline (textarea)
<TextField
  label="Message"
  multiline
  rows={4}
/>

// Controlled
const [value, setValue] = useState('');
<TextField
  label="Controlled"
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | label | string | - | Input label | | type | 'text' \| 'email' \| 'password' \| 'number' | 'text' | Input type | | variant | 'outlined' \| 'filled' | 'outlined' | Visual style | | error | boolean | false | Error state | | helperText | string | - | Helper/error text | | disabled | boolean | false | Disable input | | required | boolean | false | Required field | | fullWidth | boolean | false | Full width | | multiline | boolean | false | Use textarea | | rows | number | - | Rows (multiline only) | | minRows | number | - | Min rows (multiline) | | maxRows | number | - | Max rows (multiline) | | value | string | - | Controlled value | | defaultValue | string | - | Uncontrolled value | | onChange | (e) => void | - | Change handler |

🎨 Theming

Customize using CSS variables:

/* your-app.css */
:root {
  /* Colors */
  --color-primary: #ff5722;
  --color-secondary: #03a9f4;

  /* Typography */
  --font-family: 'Roboto', sans-serif;
  --font-size-base: 16px;

  /* Spacing */
  --spacing-unit: 10px;

  /* Borders */
  --border-radius: 8px;
}

Import after the design system CSS:

import 'betty-design-system/styles.css';
import './your-app.css'; // Your overrides

📊 Bundle Size

| Import Method | Size (gzipped) | Tree-shakeable | |--------------|----------------|----------------| | Single component | ~3-5KB | ✅ Yes | | Multiple components | ~8-15KB | ✅ Yes | | Full library | ~50KB | ❌ No |

// ✅ Recommended: Tree-shakeable
import { Button, TextField } from 'betty-design-system';

// ⚠️ Avoid: Imports everything
import * as Betty from 'betty-design-system';

♿ Accessibility

All components follow WCAG 2.1 AA guidelines:

✅ Keyboard navigation
✅ Screen reader support
✅ Proper ARIA attributes
✅ Focus management
✅ Color contrast compliance (4.5:1 for text, 3:1 for UI)

🧪 TypeScript

Fully typed with TypeScript 5. Export all prop types:

import type { ButtonProps, TextFieldProps } from 'betty-design-system';

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

Type-safe Props

TypeScript prevents invalid prop combinations:

// ✅ Valid
<TextField multiline rows={4} />

// ❌ Type error: can't use 'rows' without multiline
<TextField rows={4} />

// ❌ Type error: can't use 'type' with multiline
<TextField multiline type="email" />

🌐 Browser Support

| Browser | Versions | |---------|----------| | Chrome | Last 2 versions | | Firefox | Last 2 versions | | Safari | Last 2 versions | | Edge | Last 2 versions |

🐛 Common Issues

Styles not loading

Problem: Components render without styles.

Solution: Import CSS in your entry point:

import 'betty-design-system/styles.css';

Controlled/Uncontrolled warnings

Problem: Console warns about switching modes.

Solution: Always use value (controlled) OR defaultValue (uncontrolled):

// ✅ Always controlled
<TextField value={text ?? ''} onChange={setText} />

// ✅ Always uncontrolled
<TextField defaultValue="initial" />

// ❌ Don't switch modes
<TextField value={editing ? text : undefined} />

🎨 Explore Components

Storybook (Interactive Documentation)

Explore components interactively with live code examples:

# Clone the monorepo
git clone https://github.com/mayallzObject/111.git
cd my-design-system

# Install dependencies
npm install

# Run Storybook
npm run storybook

Open http://localhost:6006 to:

View all components with live examples
Interact with props in real-time
Test accessibility with a11y addon
Copy code snippets

Demo App

See components in a real application:

# Run the demo app
npm run dev

Open http://localhost:5173 to see:

Real-world usage examples
Form validation patterns
Theme customization
Responsive layouts

🎨 Design Tokens (Cross-Platform)

Export design tokens as JSON for use across platforms (iOS, Android, Figma, Flutter, etc.):

# Generate design-tokens.json file
npm run build:tokens

This creates a design-tokens.json file with all design tokens (colors, spacing, typography, shadows, etc.) in a platform-agnostic format.

Using Tokens in Other Platforms

Style Dictionary (iOS/Android):

# Install Style Dictionary
npm install style-dictionary

# Transform tokens to native formats
style-dictionary build

Figma Tokens Plugin:

// Import design-tokens.json into Figma Tokens plugin
// https://www.figma.com/community/plugin/843461159747178978/Figma-Tokens

Direct JSON Import:

// Import in JavaScript/TypeScript
import tokens from 'betty-design-system/design-tokens.json';

const primaryColor = tokens.colors.palettes.default.light.primary;
const spacing = tokens.spacing.md;

📖 Documentation

Architecture - Design decisions & trade-offs
Contributing - Development guide & best practices
Changelog - Version history

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

betty-design-system

📦 Installation

🚀 Quick Start

⚠️ Important: Import CSS Styles

Setup Examples

Vite

Next.js (App Router)

Next.js (Pages Router)

📚 Available Components

Public API Components

Advanced/Internal Components

📖 Component Documentation

Button

TextField

🎨 Theming

📊 Bundle Size

♿ Accessibility

🧪 TypeScript

Type-safe Props

🌐 Browser Support

🐛 Common Issues

Styles not loading

Controlled/Uncontrolled warnings

🎨 Explore Components

Storybook (Interactive Documentation)

Demo App

🎨 Design Tokens (Cross-Platform)

Using Tokens in Other Platforms

📖 Documentation

🤝 Contributing

📄 License