🎨 stp-ui-kit

A comprehensive React UI Kit with 50+ production-ready components for the Smartestprep platform. Built with TypeScript, Tailwind CSS, and SCSS for consistent design and rapid development.

✨ Features

• 🎨 50+ Components - Display, Form, Feedback, Layout, Navigation, Data
• 🎯 Design System - Comprehensive design tokens (spacing, colors, typography)
• 📱 Responsive - Mobile-first with built-in breakpoints
• 🔧 TypeScript - Full type safety with strict mode
• 🎭 Theming - CSS custom properties for easy theming
• 🚀 Tree-shakeable - ES modules for optimal bundle size
• 📚 Storybook - Interactive component documentation
• 🔥 Hot Reload - Watch mode for seamless development with npm link

📦 Installation

npm install stp-ui-kit
# or
yarn add stp-ui-kit
# or
pnpm add stp-ui-kit

🚀 Quick Start

// Import styles once in your app entry (main.tsx or App.tsx)
// Import and use components
import { Button, Input, Modal, Typography } from "stp-ui-kit";
import "stp-ui-kit/styles";

export default function App() {
  return (
    <div>
      <Typography variant='h1'>Welcome</Typography>
      <Input
        label='Email'
        placeholder='Enter your email'
      />
      <Button variant='primary'>Get Started</Button>
    </div>
  );
}

Using Design Tokens

In SCSS files:

@use "stp-ui-kit/styles/variables" as stp;

.my-component {
  padding: stp.$space-400; // 16px
  border-radius: stp.$border-radius-100; // 4px
  color: var(--color-neutral-800);
}

In JavaScript/TypeScript:

import { breakpoints, spacing, typography } from "stp-ui-kit/tokens";

const styles = {
  padding: spacing["space-400"], // '16px'
};

📚 Documentation

• COMPONENTS.md - Complete component reference with all 50+ components
• USAGE_GUIDE.md - Comprehensive usage guide with examples
• Layout System:
  • PAGE_BUILDING_GUIDE.md - Complete guide to building pages
  • PAGE_CHEAT_SHEET.md - Quick reference cheat sheet
  • SPACING_GUIDE.md - Visual spacing & layout guide
  • SCROLL_OVERFLOW_GUIDE.md - Scroll behavior & overflow handling
  • MIGRATION_GUIDE.md - ⚠️ Migration guide from old API to v0.0.117+
  • page-building-schema.json - JSON schema for AI tools
• CLAUDE.md - Instructions for AI assistants (Claude Code)
• Storybook - Interactive demos (run npm run storybook)

📂 Project Structure

src/
 ├─ assets/            # custom icons and static assets
 ├─ components/        # UI components
 │   ├─ data/
 │   ├─ display/
 │   ├─ feedback/
 │   ├─ form/
 │   ├─ layout/
 │   ├─ navigation/
 │   └─ ui/
 ├─ lib/               # helpers, utils
 ├─ styles/            # global styles, tokens, variables
 │   ├─ _variables.scss
 │   ├─ main.scss
 │   └─ tokens.ts
 ├─ App.tsx            # playground / dev entry
 └─ index.ts           # main export file

🛠 Tech Stack

• React 18+ / 19+ – core UI framework
• TypeScript – strongly typed components
• TailwindCSS 4 + SCSS – styling and design tokens
• React Hook Form – form handling integration
• Storybook 8 – interactive component documentation
• Vite – development & build tooling

📖 Documentation

Run Storybook to explore and test components interactively:

npm run storybook

Build the static Storybook docs:

npm run build-storybook

🧑‍💻 Development

• Start in dev mode

  npm run dev

• Build library

  npm run build

• Lint & format

  npm run lint
  npm run format

• Generate tokens

  npm run generate-tokens

🔑 Principles

• Fully typed components (.ts / .tsx only)
• Consistent design system powered by tokens according to Figma designs
• Use named exports only (export const)
• Remove unused/deprecated components over time
• Do not add new dependencies unless absolutely necessary (to avoid making the project heavy)

📦 Project Releases

• Always upgrade the version in package.json before publishing
• Do not run npm publish for every minor change
• Always run npm run build before publishing
• All changes must be commited into repository

🛠 Local Development with Hot Reload

When developing stp-ui-kit and testing in another project:

# 1. In stp-ui-kit directory
npm link
npm run build:watch  # Keep this running - auto-rebuilds on changes!

# 2. In your project directory
npm link stp-ui-kit
npm start

# Changes in stp-ui-kit will now auto-reflect in your project! 🔥

No need to unlink/relink - build:watch provides hot reload for linked packages.

📤 Publishing

• Always run npm run build before publishing
• Update version in package.json before npm publish
• Commit all changes to repository
• Run npm run format and npm run lint before committing

🤝 Contributing

1. Clone the repo
2. Install dependencies with npm install
3. Run Storybook (npm run storybook)
4. Add or update a component inside src/components
5. Submit a pull request 🎉

📜 License

MIT © Smartestprep