@maxsteinwender/sort-ui 1.0.7 → 1.0.8

package/guidelines/icon-discovery.md

@@ -0,0 +1,247 @@
+# Icon Discovery and Usage Guidelines
+
+This document explains how to find and use icons in the SortUI Design System.
+
+## Icon Package
+
+**Bundled with:** `@maxsteinwender/sort-ui` (Remix Icons — no separate install)
+**Import:** Icons are loaded automatically via the main CSS bundle
+**Location in package:** `node_modules/@maxsteinwender/sort-ui/dist/styles.css` (font-icon classes)
+
+**DO NOT install `lucide-react`, `heroicons`, `react-icons`, or any other icon package.** Remix Icons is the single source.
+
+## Naming Convention
+
+```
+ri-{icon-name}-{variant}
+```
+
+**Variants:**
+- `-line` — outlined/stroke style (most common)
+- `-fill` — filled/solid style
+
+**Examples:**
+- `ri-user-line`, `ri-user-fill`
+- `ri-settings-line`, `ri-settings-fill`
+- `ri-arrow-right-line`, `ri-arrow-right-fill`
+- `ri-check-line`, `ri-check-fill`
+- `ri-close-line`, `ri-close-fill`
+
+## Usage
+
+Icons are rendered as `<i>` elements with Remix Icon class names:
+
+```tsx
+<i className="ri-user-line" />
+<i className="ri-settings-fill" />
+<i className="ri-arrow-right-line" />
+```
+
+**Color via icon tokens** (note: icon colors use `text-sui-icon-*`):
+```tsx
+<i className="ri-user-fill text-sui-icon-default" />
+<i className="ri-error-warning-line text-sui-icon-destructive" />
+<i className="ri-check-line text-sui-icon-success" />
+<i className="ri-information-line text-sui-icon-informative" />
+<i className="ri-alarm-warning-line text-sui-icon-warning" />
+<i className="ri-user-line text-sui-icon-subtle" />
+```
+
+**Within SortUI components:**
+```tsx
+// Button with lead icon
+<Button>
+  <i className="ri-search-line" />
+  Search
+</Button>
+
+// Icon-only button — MUST have aria-label
+<Button iconOnly aria-label="Settings">
+  <i className="ri-settings-line" />
+</Button>
+
+// InputField with lead icon
+<InputField
+  leadIcon={<i className="ri-mail-line" />}
+  placeholder="Email"
+/>
+```
+
+## Sizing
+
+Most SortUI components handle icon sizing automatically. When direct size control is needed, use Tailwind text-size utilities — do NOT use `ri-xs` / `ri-sm` helpers:
+
+```tsx
+<i className="ri-user-line text-sm" />
+<i className="ri-user-line text-base" />
+<i className="ri-user-line text-lg" />
+<i className="ri-user-line text-xl" />
+<i className="ri-user-line text-2xl" />
+```
+
+## How to Find Icons
+
+**CRITICAL:** Do NOT guess icon names. Icon names must be verified before use.
+
+### Method 1: Search the bundled CSS
+
+The bundled CSS contains every available icon class. Search `node_modules/@maxsteinwender/sort-ui/dist/styles.css` for keywords:
+
+```bash
+grep -o "\.ri-[a-z0-9-]*user[a-z0-9-]*:before" node_modules/@maxsteinwender/sort-ui/dist/styles.css
+grep -o "\.ri-[a-z0-9-]*calendar[a-z0-9-]*:before" node_modules/@maxsteinwender/sort-ui/dist/styles.css
+```
+
+Example workflow:
+1. Identify keyword (e.g., "calendar")
+2. Search styles.css for `ri-calendar`
+3. Find matching icons: `ri-calendar-line`, `ri-calendar-fill`, `ri-calendar-event-line`, `ri-calendar-2-line`, etc.
+
+### Method 2: Official Remix Icon reference
+
+The design system uses **Remix Icon v4.9.1**. All icons from Remix Icon 4.x are available.
+
+Reference: https://remixicon.com/
+
+**Common icon categories:**
+- **System:** settings, more, menu, close, check, error, information, question, warning
+- **Arrows:** arrow-up, arrow-down, arrow-left, arrow-right, chevron-up, chevron-down
+- **Media:** play, pause, stop, volume, image, camera, video
+- **User:** user, team, account, contacts, profile
+- **Files:** file, folder, attachment, download, upload
+- **Communication:** mail, message, chat, notification, phone
+- **Design:** pencil, brush, palette, format, layout
+- **Business:** briefcase, bank, wallet, price-tag, shopping-cart
+- **Maps:** map, pin, location, navigation, compass
+- **Device:** phone, tablet, computer, keyboard, mouse
+- **Weather:** sun, moon, cloud, rain, snow
+
+## Common Icon Patterns
+
+### Navigation icons
+```tsx
+<i className="ri-arrow-left-line" />
+<i className="ri-arrow-right-line" />
+<i className="ri-arrow-up-line" />
+<i className="ri-arrow-down-line" />
+<i className="ri-chevron-left-line" />
+<i className="ri-chevron-right-line" />
+<i className="ri-menu-line" />
+<i className="ri-close-line" />
+<i className="ri-more-line" />
+```
+
+### Action icons
+```tsx
+<i className="ri-add-line" />
+<i className="ri-subtract-line" />
+<i className="ri-edit-line" />
+<i className="ri-delete-bin-line" />
+<i className="ri-save-line" />
+<i className="ri-download-line" />
+<i className="ri-upload-line" />
+<i className="ri-share-line" />
+<i className="ri-search-line" />
+<i className="ri-filter-line" />
+```
+
+### Status icons
+```tsx
+<i className="ri-check-line text-sui-icon-success" />
+<i className="ri-close-circle-line text-sui-icon-destructive" />
+<i className="ri-error-warning-line text-sui-icon-warning" />
+<i className="ri-information-line text-sui-icon-informative" />
+<i className="ri-checkbox-circle-line text-sui-icon-success" />
+```
+
+### User / Social icons
+```tsx
+<i className="ri-user-line" />
+<i className="ri-user-fill" />
+<i className="ri-team-line" />
+<i className="ri-account-circle-line" />
+<i className="ri-heart-line" />
+<i className="ri-star-line" />
+<i className="ri-thumb-up-line" />
+```
+
+### Communication icons
+```tsx
+<i className="ri-mail-line" />
+<i className="ri-message-line" />
+<i className="ri-chat-line" />
+<i className="ri-notification-line" />
+<i className="ri-phone-line" />
+<i className="ri-send-plane-line" />
+```
+
+### File / Document icons
+```tsx
+<i className="ri-file-line" />
+<i className="ri-folder-line" />
+<i className="ri-attachment-line" />
+<i className="ri-file-text-line" />
+<i className="ri-file-pdf-line" />
+<i className="ri-image-line" />
+```
+
+### Settings / System icons
+```tsx
+<i className="ri-settings-line" />
+<i className="ri-equalizer-line" />
+<i className="ri-tools-line" />
+<i className="ri-lock-line" />
+<i className="ri-eye-line" />
+<i className="ri-eye-off-line" />
+```
+
+## DO / DON'T
+
+**DO:**
+```tsx
+<i className="ri-user-line" />
+<i className="ri-check-line" />    {/* outlined */}
+<i className="ri-check-fill" />    {/* filled */}
+
+// Icon-only button with aria-label
+<Button iconOnly aria-label="Settings">
+  <i className="ri-settings-line" />
+</Button>
+```
+
+**DON'T:**
+```tsx
+// ❌ Guessed icon names
+<i className="ri-profile-line" />   {/* doesn't exist — use ri-user-line */}
+
+// ❌ Installing alternate icon packages
+import { User } from "lucide-react";
+
+// ❌ Icon-only button without aria-label
+<Button iconOnly>
+  <i className="ri-settings-line" />
+</Button>
+```
+
+## Verifying Icon Existence
+
+Before using an icon in generated code:
+
+1. **Search the bundled CSS** for the icon class
+2. **Check the pattern** matches `ri-{name}-line` or `ri-{name}-fill`
+3. **If uncertain**, pick a similar known icon (e.g., `ri-user-line` instead of guessing `ri-profile-line`)
+
+```bash
+# Verify ri-calendar-event-line exists
+grep "ri-calendar-event-line:before" node_modules/@maxsteinwender/sort-ui/dist/styles.css
+# ✓ If output contains "content:" the icon is valid
+```
+
+## Reminders
+
+- **Remix Icons are bundled** — no separate package install
+- **Do NOT install `lucide-react`** or other icon packages
+- **Always verify icon existence** before use
+- **Use `-line` for outlined**, `-fill` for solid
+- **Provide `aria-label`** for icon-only buttons
+- **Icon color via `text-sui-icon-*` tokens** (never raw hex)

package/guidelines/setup.md

@@ -0,0 +1,343 @@
+# SortUI Design System — Setup Instructions
+
+Complete setup guide for integrating `@maxsteinwender/sort-ui` into your project.
+
+---
+
+## Package Manager
+
+**Use npm.** This package is authored and published using npm. Examples in these guidelines always show `npm install`. Do not suggest `pnpm add` or `yarn add`.
+
+---
+
+## Package Installation
+
+**CRITICAL**: You MUST explicitly install every package listed below as a direct dependency, exactly as written. Transitive availability does NOT count as installed.
+
+```bash
+npm install @maxsteinwender/sort-ui
+```
+
+Add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@maxsteinwender/sort-ui": "^1.0.8"
+  }
+}
+```
+
+**Peer dependencies (required):**
+- `react` >= 19.0.0
+- `react-dom` >= 19.0.0
+
+If using form components (React Hook Form wrappers), install:
+
+```bash
+npm install react-hook-form
+```
+
+---
+
+## CSS Import
+
+Import the bundled CSS **once** at your app entry point (e.g., root layout, `_app.tsx`, or `main.tsx`):
+
+```tsx
+import "@maxsteinwender/sort-ui/styles.css";
+```
+
+This loads:
+- Design tokens (CSS custom properties)
+- Remix Icons (font icons, bundled)
+- Component styles
+- Redaction font (bundled)
+- Geist Sans + Geist Mono (bundled)
+
+**IMPORTANT:** Only import this CSS file once. Do not import it in multiple files.
+
+---
+
+## Theme Configuration — All 4 Themes
+
+Apply ONE of these classes to the root `<html>` (or `<body>`) element. The SortUI Design System ships **four** themes and all four must render correctly for any generated UI.
+
+| Theme Class | Color Scheme | Mode |
+|-------------|--------------|------|
+| `light` | zinc/blue | light (default) |
+| `dark` | zinc/blue | dark |
+| `theme-2` | neutral/orange | light |
+| `theme-2-dark` | neutral/orange | dark |
+
+**Example — light (default):**
+```tsx
+// app/layout.tsx
+import "@maxsteinwender/sort-ui/styles.css";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className="light">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Example — dark:**
+```tsx
+<html lang="en" className="dark">
+  <body>{children}</body>
+</html>
+```
+
+**Example — theme-2 (neutral/orange, light):**
+```tsx
+<html lang="en" className="theme-2">
+  <body>{children}</body>
+</html>
+```
+
+**Example — theme-2-dark (neutral/orange, dark):**
+```tsx
+<html lang="en" className="theme-2-dark">
+  <body>{children}</body>
+</html>
+```
+
+**Dynamic theme switching:**
+```tsx
+"use client";
+
+import { useEffect, useState } from "react";
+
+type Theme = "light" | "dark" | "theme-2" | "theme-2-dark";
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<Theme>("light");
+
+  useEffect(() => {
+    document.documentElement.className = theme;
+  }, [theme]);
+
+  return <>{children}</>;
+}
+```
+
+Theme variants swap CSS variables automatically — never hard-code theme-specific class logic in components.
+
+---
+
+## Tailwind CSS v3 Setup
+
+**IMPORTANT:** SortUI targets **Tailwind CSS v3** (`^3.4.1`). It is **NOT** Tailwind v4. Do not use the v4 `@theme` directive or v4-only APIs. The package ships a **Tailwind v3 preset** that extends Tailwind with SUI design tokens.
+
+### 1. Install Tailwind CSS v3
+
+```bash
+npm install -D tailwindcss@^3.4.1 postcss autoprefixer
+```
+
+### 2. Configure Tailwind
+
+Import the SortUI preset in your `tailwind.config.ts` (or `tailwind.config.js`):
+
+```ts
+// tailwind.config.ts
+import type { Config } from "tailwindcss";
+import sortUiPreset from "@maxsteinwender/sort-ui/tailwind-preset";
+
+const config: Config = {
+  presets: [sortUiPreset],
+  content: [
+    "./src/app/**/*.{ts,tsx,js,jsx}",
+    "./src/components/**/*.{ts,tsx,js,jsx}",
+  ],
+};
+
+export default config;
+```
+
+**JavaScript version:**
+```js
+// tailwind.config.js
+const sortUiPreset = require("@maxsteinwender/sort-ui/tailwind-preset");
+
+module.exports = {
+  presets: [sortUiPreset],
+  content: [
+    "./src/app/**/*.{ts,tsx,js,jsx}",
+    "./src/components/**/*.{ts,tsx,js,jsx}",
+  ],
+};
+```
+
+### 3. Add Tailwind v3 directives
+
+Create or update your global CSS file (e.g., `globals.css`):
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**IMPORTANT:** Import `@maxsteinwender/sort-ui/styles.css` BEFORE your global CSS file:
+
+```tsx
+// app/layout.tsx
+import "@maxsteinwender/sort-ui/styles.css";
+import "./globals.css";
+```
+
+---
+
+## Tailwind Utility Classes (correct naming)
+
+The SortUI preset exposes utility classes that follow the `sui-` prefix rules in `Guidelines.md`:
+
+| Token Category | Prefix? | Tailwind Classes | Example |
+|----------------|---------|------------------|---------|
+| Background | `sui-` | `bg-sui-bg-default`, `bg-sui-bg-subtle` | `<div className="bg-sui-bg-default" />` |
+| Text | `sui-` | `text-sui-text-default`, `text-sui-text-subtle` | `<p className="text-sui-text-default" />` |
+| Border color | `sui-` | `border-sui-border-default` | `<div className="border border-sui-border-default" />` |
+| Icon color | `sui-` | `text-sui-icon-default`, `text-sui-icon-destructive` | `<i className="ri-user-line text-sui-icon-subtle" />` |
+| Spacing | `sui-` | `p-sui-24`, `gap-sui-16`, `m-sui-8`, `space-y-sui-16` | `<div className="p-sui-24 gap-sui-16" />` |
+| Radius | **no prefix** | `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md` | `<div className="rounded-lg" />` |
+| Shadow | **no prefix** | `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md` | `<div className="shadow-card" />` |
+| Border width | **no prefix** | `border`, `border-md`, `border-lg` | `<div className="border-md" />` |
+
+❌ `shadow-sui-default`, `shadow-sui-card`, `shadow-sm`, `shadow-md`, `shadow-lg` — **these do not exist.**
+❌ `rounded-sui-md`, `rounded-sui-lg`, `rounded-sui-full` — **these do not exist.**
+
+---
+
+## Toast Provider Setup
+
+If using the Toast component (powered by Sonner), add the `<Toaster />` component to your root layout:
+
+```tsx
+// app/layout.tsx
+import { Toaster } from "@maxsteinwender/sort-ui";
+import "@maxsteinwender/sort-ui/styles.css";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className="light">
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
+  );
+}
+```
+
+**Usage:**
+```tsx
+import { toast } from "sonner";
+
+toast.success("Operation successful");
+toast.error("Something went wrong");
+```
+
+---
+
+## Tooltip Provider Setup
+
+If using Tooltip components, wrap your app with `<TooltipProvider>`:
+
+```tsx
+import { TooltipProvider } from "@maxsteinwender/sort-ui";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className="light">
+      <body>
+        <TooltipProvider>{children}</TooltipProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## Form Integration
+
+For form components, install `react-hook-form` and import from the `/form` entry point:
+
+```bash
+npm install react-hook-form
+```
+
+```tsx
+import { useForm } from "react-hook-form";
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@maxsteinwender/sort-ui/form";
+import { InputField, Button } from "@maxsteinwender/sort-ui";
+
+const form = useForm({ defaultValues: { email: "" } });
+
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-col gap-sui-16">
+    <FormField
+      control={form.control}
+      name="email"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <InputField {...field} placeholder="you@example.com" />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <Button type="submit">Submit</Button>
+  </form>
+</Form>
+```
+
+---
+
+## Icon Usage
+
+Icons are bundled with the design system (Remix Icons). No additional installation required.
+
+```tsx
+<i className="ri-user-line" />
+<i className="ri-settings-fill" />
+
+<Button>
+  <i className="ri-search-line" />
+  Search
+</Button>
+```
+
+**DO NOT install `lucide-react`, `heroicons`, `react-icons`, or any other icon package.**
+
+See `icon-discovery.md` for the icon verification workflow.
+
+---
+
+## TypeScript Support
+
+The package ships TypeScript definitions; no additional setup required.
+
+```tsx
+import type { ButtonProps, InputFieldProps } from "@maxsteinwender/sort-ui";
+```
+
+---
+
+## Setup Checklist
+
+- [ ] Installed `@maxsteinwender/sort-ui` via **npm** (not pnpm/yarn)
+- [ ] Imported `@maxsteinwender/sort-ui/styles.css` once at app entry
+- [ ] Set one of the 4 theme classes on `<html>`: `light`, `dark`, `theme-2`, or `theme-2-dark`
+- [ ] Configured **Tailwind v3** with SortUI preset (not v4)
+- [ ] Added `@tailwind base; @tailwind components; @tailwind utilities;` to global CSS
+- [ ] Added `<Toaster />` to root layout (if using toasts)
+- [ ] Wrapped app with `<TooltipProvider>` (if using tooltips)
+- [ ] Installed `react-hook-form` (if using form components)
+- [ ] Did NOT install `lucide-react` or any additional icon package