@maxsteinwender/sort-ui 1.1.0 → 1.1.1

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="public/visuals/Key Visual.png" alt="Hero Image" width="100%" />
+</p>
+
 # Sort UI Design System
 
 A coded design system based on the [Sort UI Kit](https://sortui.company) — Figma components translated into production-ready Next.js components, documented in Storybook.

package/guidelines/Guidelines.md

@@ -0,0 +1,294 @@
+# SortUI Design System Guidelines
+
+This is the main hub for all SortUI Design System (`@maxsteinwender/sort-ui`) guidelines. These files are authoritative — prefer them over any heuristics inferred from bundled source code.
+
+---
+
+## Reading order
+
+Always read first:
+- `Guidelines.md` — this file; the main hub and entry point
+- `setup.md` — required project configuration, providers, and CSS imports
+- `tokens.md` — foundational design tokens (color, typography, spacing, shadow, radius)
+
+Read on-demand:
+- `components.md` — read BEFORE using any design-system component
+- `icon-discovery.md` — read BEFORE using any icons
+- `styles.md` — read when building page layouts or applying custom spacing
+
+---
+
+## Critical rules (read before generating any code)
+
+1. **Tailwind version is v3** (`^3.4.1`). It is **NOT** Tailwind v4. Never emit `@theme` directives or v4-only syntax.
+2. **Package manager is npm.** Never suggest `pnpm` or `yarn` install commands — use `npm install`.
+3. **Selective `sui-` prefix.** Colors and spacing carry `sui-`; shadows and radius do NOT.
+   - ✅ `text-sui-text-default`, `bg-sui-bg-subtle`, `gap-sui-16`, `p-sui-24`
+   - ✅ `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md`
+   - ✅ `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md`
+   - ❌ `shadow-sui-default`, `shadow-sui-card`, `shadow-sm`, `shadow-md`
+   - ❌ `rounded-sui-md`, `rounded-sui-lg`
+4. **Reuse existing SortUI components.** Never inline custom markup when a component exists — use `Badge`, `Avatar`, `ProgressBar`, `Button`, `InputField`, `Card`, etc.
+5. **Charts: `isAnimationActive={false}` on every Recharts series.** Recharts 2.x animations rely on removed React 19 APIs and render empty without this prop.
+6. **Icons: Remix Icons only.** Syntax `<i className="ri-{name}-{variant}" />`. Never install `lucide-react`, `heroicons`, or any other icon package.
+7. **All 4 themes.** Every generated UI must render correctly in `light`, `dark`, `theme-2`, and `theme-2-dark`.
+
+---
+
+## Companion guideline files
+
+| File | Focus |
+|---|---|
+| `setup.md` | Installation, Tailwind v3 config, CSS imports, provider setup, all 4 theme classes |
+| `tokens.md` | Design tokens — colors, typography, shadow, border, radius, spacing (correct class names) |
+| `styles.md` | Spacing, layout primitives, responsive patterns (Tailwind v3 breakpoints) |
+| `components.md` | Component imports, props, variants, and composition patterns |
+| `icon-discovery.md` | Remix Icon naming, discovery, and verification |
+
+---
+
+## Before using an icon
+
+1. Check `icon-discovery.md` for verification workflow
+2. Do NOT guess icon names — verify the icon exists first
+3. If an icon doesn't exist, pick a different one and verify
+
+---
+
+## General Guidelines
+
+### Code Quality
+- Use responsive layouts with Flexbox and Grid by default
+- Avoid absolute positioning unless necessary
+- Keep components focused and single-purpose
+- Extract reusable logic into helper functions
+
+### Component Usage
+- Always import components from the correct entry points:
+  - Main: `@maxsteinwender/sort-ui`
+  - Form (React Hook Form wrappers): `@maxsteinwender/sort-ui/form`
+- Prefer composition over complex prop APIs
+- **Reuse existing SortUI components instead of custom markup.**
+
+### Accessibility
+- Provide `aria-label` for icon-only buttons
+- Use semantic HTML elements
+- Ensure proper heading hierarchy
+- Add descriptive labels for form inputs
+
+---
+
+## Design System Guidelines
+
+### Colors & Theming
+- Use semantic tokens (`text-sui-text-default`, `bg-sui-bg-subtle`) over raw hex values
+- Tokens automatically adapt to theme changes
+- Apply ONE theme class to `<html>` or `<body>`: `light`, `dark`, `theme-2`, `theme-2-dark`
+
+### Typography
+- Default font: Geist Sans (bundled)
+- Code font: Geist Mono (bundled)
+- Display/quote font: Redaction (bundled)
+- Use Tailwind size utilities: `text-xs` through `text-9xl`
+
+### Spacing
+- Use SortUI spacing tokens: `gap-sui-16`, `p-sui-24`, `mx-sui-32`, `space-y-sui-16`
+- Common patterns:
+  - Form field gap: `gap-sui-16`
+  - Card padding: `p-sui-24`
+  - Section gap: `gap-sui-32` to `gap-sui-48`
+
+### Shadow & Radius (NO `sui-` prefix)
+- Shadows: `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md`
+- Radius: `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md`
+- Never use `shadow-sm`, `shadow-md`, `shadow-lg`, or arbitrary `shadow-[…]` values
+
+### Responsive Design (Tailwind v3 breakpoints)
+- Mobile-first approach
+- Breakpoints: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px), `2xl` (1536px)
+- Example: `p-sui-16 md:p-sui-24 lg:p-sui-32`
+
+---
+
+## Component Best Practices
+
+### Buttons
+- `variant`: `default`, `ghost`, `destructive`, `secondary`, `outline`, `ghost-muted`
+- `size`: `2xs`, `xs`, `sm`, `md`, `lg`
+- Icon-only buttons **MUST** have `aria-label`
+- Use `loading` prop for async actions (don't add manual spinners)
+
+### Forms
+- Use `InputField` with `error` prop for validation feedback
+- Group related fields with `gap-sui-16`
+- Use `required` prop to show asterisk on labels
+- Integrate with React Hook Form via `@maxsteinwender/sort-ui/form`
+
+### Cards
+- Use semantic slots: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`
+- Use `CardCover` with `flush` prop for edge-to-edge images
+- `variant="default"` has border + shadow; `variant="flat"` removes them
+
+### Icons
+- Always verify icon exists before using (see `icon-discovery.md`)
+- Use `-line` for outlined, `-fill` for solid
+- Syntax: `<i className="ri-{name}-line" />`
+- Do NOT install additional icon packages
+
+### Charts (Recharts)
+- Always set `isAnimationActive={false}` on every series (`Line`, `Bar`, `Area`, `Pie`, etc.)
+- Wrap in `ChartContainer` from `@maxsteinwender/sort-ui` with a `ChartConfig`
+- Use chart color tokens: `var(--chart-1)` through `var(--chart-5)`
+
+---
+
+## Common Patterns
+
+### Form with validation
+```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>
+```
+
+### Modal dialog
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm</DialogTitle>
+      <DialogDescription>This action cannot be undone.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Data display with reused SortUI components
+```tsx
+// ✅ DO — reuse Avatar + Badge
+<div className="flex items-center gap-sui-12">
+  <Avatar
+    src="/user.jpg"
+    fallback="JD"
+    size="md"
+    bottomBadge
+    bottomBadgeVariant="online"
+    bottomBadgeLabel="Online"
+  />
+  <div>
+    <p className="font-semibold text-sui-text-default">John Doe</p>
+    <Badge color="green" size="sm">Active</Badge>
+  </div>
+</div>
+
+// ❌ DON'T — inline markup instead of reusing components
+<div className="flex items-center gap-sui-12">
+  <img src="/user.jpg" className="w-10 h-10 rounded-full" />
+  <div>
+    <p className="font-semibold">John Doe</p>
+    <span className="inline-flex bg-green-100 text-green-800 px-2 py-1 rounded-full text-xs">Active</span>
+  </div>
+</div>
+```
+
+### Chart with required `isAnimationActive={false}`
+```tsx
+import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from "@maxsteinwender/sort-ui";
+import { LineChart, Line, Bar } from "recharts";
+
+const config: ChartConfig = {
+  revenue: { label: "Revenue", color: "var(--chart-1)" },
+};
+
+<ChartContainer config={config}>
+  <LineChart data={data}>
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Line dataKey="revenue" stroke="var(--color-revenue)" isAnimationActive={false} />
+    <Bar dataKey="sales" fill="var(--chart-2)" isAnimationActive={false} />
+  </LineChart>
+</ChartContainer>
+```
+
+---
+
+## DO / DON'T
+
+**DO:**
+- ✓ Use `npm install` (not `pnpm add`)
+- ✓ Treat Tailwind as v3 (not v4)
+- ✓ Use `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md`
+- ✓ Use `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md`
+- ✓ Use `sui-` prefix for colors and spacing (`bg-sui-bg-default`, `gap-sui-16`)
+- ✓ Reuse existing SortUI components (`Badge`, `Avatar`, `ProgressBar`, `Button`)
+- ✓ Provide `aria-label` for icon-only buttons
+- ✓ Set `isAnimationActive={false}` on all Recharts series
+- ✓ Test all 4 themes (`light`, `dark`, `theme-2`, `theme-2-dark`)
+
+**DON'T:**
+- ✗ Use `pnpm add` or `yarn add`
+- ✗ Assume Tailwind v4 or emit `@theme` directives
+- ✗ Use `shadow-sui-*`, `shadow-sm`, `shadow-md`, `shadow-lg`
+- ✗ Use `rounded-sui-*`
+- ✗ Hard-code colors (`bg-[#fafafa]`) or spacing (`gap-[16px]`)
+- ✗ Inline custom markup when a SortUI component exists
+- ✗ Omit `isAnimationActive={false}` on Recharts series
+- ✗ Guess icon names without verification
+- ✗ Install `lucide-react` or other icon packages
+
+---
+
+## Quick Reference
+
+| Need | Read |
+|------|------|
+| Setup / install / providers | `setup.md` |
+| Color, typography, shadow, radius tokens | `tokens.md` |
+| Spacing and layout | `styles.md` |
+| Component API | `components.md` |
+| Icon usage and discovery | `icon-discovery.md` |
+
+---
+
+## Common Mistakes to Avoid
+
+| ❌ Wrong | ✅ Correct |
+|---|---|
+| `pnpm add @maxsteinwender/sort-ui` | `npm install @maxsteinwender/sort-ui` |
+| "Tailwind v4" / `@theme` directive | Tailwind v3 / `tailwind.config.ts` preset |
+| `shadow-sui-default`, `shadow-sui-card` | `shadow-default`, `shadow-card` |
+| `shadow-md`, `shadow-lg` | `shadow-default` or `shadow-card` |
+| `rounded-sui-md`, `rounded-sui-lg` | `rounded-md`, `rounded-lg` |
+| `bg-[#fafafa]` | `bg-sui-bg-subtle` |
+| `gap-[16px]` | `gap-sui-16` |
+| `<i className="lucide-user" />` | `<i className="ri-user-line" />` |
+| `<Line stroke="..." />` (Recharts) | `<Line stroke="..." isAnimationActive={false} />` |
+| Inline `<span class="bg-green-100">Active</span>` | `<Badge color="green">Active</Badge>` |
+| `<img src="/u.jpg" class="rounded-full" />` | `<Avatar src="/u.jpg" fallback="MS" size="md" />` |