npm - @maxsteinwender/sort-ui - Versions diffs - 1.1.0 → 1.1.1 - Mend

@maxsteinwender/sort-ui 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +4 -0
package/guidelines/Guidelines.md +294 -0
package/guidelines/components.md +406 -0
package/guidelines/icon-discovery.md +247 -0
package/guidelines/setup.md +343 -0
package/guidelines/styles.md +356 -0
package/guidelines/tokens.md +354 -0
package/package.json +3 -2

package/guidelines/tokens.md ADDED Viewed

@@ -0,0 +1,354 @@
+# Design Tokens and CSS Guidelines
+Design tokens, CSS custom properties, and theming in SortUI. Uses **Tailwind v3** (`^3.4.1`) — never v4.
+## Token Format
+Tokens are consumed as **CSS custom properties** (variables) and **Tailwind v3 utility classes**.
+```css
+/* CSS custom properties */
+color: var(--text-default);
+background: var(--bg-subtle);
+border-radius: var(--radius-md);
+box-shadow: var(--shadow-card);
+/* Tailwind v3 classes (via SortUI preset) */
+<div className="bg-sui-bg-default text-sui-text-default rounded-md shadow-card p-sui-24" />
+```
+### `sui-` prefix rules (CRITICAL)
+The `sui-` prefix is applied **selectively**. Memorize this table.
+| Category | Prefix? | Correct | Wrong |
+|---|---|---|---|
+| Color — text | yes | `text-sui-text-default`, `text-sui-text-muted` | `text-default` |
+| Color — background | yes | `bg-sui-bg-default`, `bg-sui-bg-subtle` | `bg-default` |
+| Color — border | yes | `border-sui-border-default` | `border-default` |
+| Color — icon | yes | `text-sui-icon-default`, `text-sui-icon-destructive` | `text-icon-default` |
+| Spacing | yes | `gap-sui-16`, `p-sui-24`, `mx-sui-32`, `space-y-sui-16` | `gap-16` |
+| Badge background | yes | `bg-sui-badge-blue`, `bg-sui-badge-red` | `bg-badge-blue` |
+| **Radius** | **no** | `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md` | ~~`rounded-sui-md`~~ |
+| **Shadow** | **no** | `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md` | ~~`shadow-sui-default`~~ ~~`shadow-md`~~ |
+| **Border width** | **no** | `border` (1px), `border-md` (1.5px), `border-lg` (2px) | ~~`border-sui-md`~~ |
+| **Font size** | **no** | `text-sm`, `text-base`, `text-2xl` | ~~`text-sui-md`~~ |
+---
+## Theming — 4 Themes
+SortUI provides **4 theme variants**. All four must render correctly for any generated UI.
+- `light` — zinc/blue, light mode (default)
+- `dark` — zinc/blue, dark mode
+- `theme-2` — neutral/orange, light mode
+- `theme-2-dark` — neutral/orange, dark mode
+**Apply theme class to `<html>` or `<body>`:**
+```tsx
+<html className="dark">
+  {/* App renders in dark theme */}
+</html>
+```
+---
+## Color Tokens
+### Text Tokens
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--text-default` | Primary text | `text-sui-text-default` |
+| `--text-subtle` | Secondary text | `text-sui-text-subtle` |
+| `--text-muted` | Tertiary text | `text-sui-text-muted` |
+| `--text-hint` | Placeholder text | `text-sui-text-hint` |
+| `--text-inverted-default` | Text on dark backgrounds | `text-sui-text-inverted-default` |
+| `--text-inverted-subtle` | Subtle text on dark | `text-sui-text-inverted-subtle` |
+| `--text-destructive` | Error/danger text | `text-sui-text-destructive` |
+| `--text-primary` | Primary brand text | `text-sui-text-primary` |
+| `--text-success` | Success text | `text-sui-text-success` |
+| `--text-warning` | Warning text | `text-sui-text-warning` |
+| `--text-informative` | Info text | `text-sui-text-informative` |
+### Background Tokens
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--bg-default` | Page/card background | `bg-sui-bg-default` |
+| `--bg-subtle` | Subtle background | `bg-sui-bg-subtle` |
+| `--bg-muted` | Muted background | `bg-sui-bg-muted` |
+| `--bg-card` | Card background | `bg-sui-bg-card` |
+| `--bg-inverted` | Dark background | `bg-sui-bg-inverted` |
+**State backgrounds:** `bg-sui-state-primary`, `bg-sui-state-primary-hover`, `bg-sui-state-destructive`, `bg-sui-state-soft`, `bg-sui-state-ghost`, `bg-sui-state-disabled`, etc.
+**Badge backgrounds (semantic color scale):**
+- `bg-sui-badge-red`, `bg-sui-badge-orange`, `bg-sui-badge-yellow`, `bg-sui-badge-lime`, `bg-sui-badge-green`, `bg-sui-badge-emerald`, `bg-sui-badge-teal`, `bg-sui-badge-cyan`, `bg-sui-badge-sky`, `bg-sui-badge-blue`, `bg-sui-badge-indigo`, `bg-sui-badge-violet`, `bg-sui-badge-purple`, `bg-sui-badge-fuchsia`, `bg-sui-badge-pink`, `bg-sui-badge-gray`, `bg-sui-badge-white`, `bg-sui-badge-inverted`
+### Border Color Tokens
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--border-default` | Default borders | `border-sui-border-default` |
+| `--border-darker` | Stronger borders | `border-sui-border-darker` |
+| `--border-strong` | Strong borders | `border-sui-border-strong` |
+| `--border-accent` | Accent borders | `border-sui-border-accent` |
+| `--border-destructive` | Error borders | `border-sui-border-destructive` |
+| `--border-informative` | Info borders | `border-sui-border-informative` |
+| `--border-success` | Success borders | `border-sui-border-success` |
+| `--border-warning` | Warning borders | `border-sui-border-warning` |
+### Icon Color Tokens
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--icon-default` | Primary icons | `text-sui-icon-default` |
+| `--icon-default-subtle` | Subtle icons | `text-sui-icon-subtle` |
+| `--icon-default-muted` | Muted icons | `text-sui-icon-muted` |
+| `--icon-default-disabled` | Disabled icons | `text-sui-icon-disabled` |
+| `--icon-inverted-default` | Icons on dark backgrounds | `text-sui-icon-inverted-default` |
+| `--icon-destructive` | Error icons | `text-sui-icon-destructive` |
+| `--icon-informative` | Info icons | `text-sui-icon-informative` |
+| `--icon-success` | Success icons | `text-sui-icon-success` |
+| `--icon-warning` | Warning icons | `text-sui-icon-warning` |
+---
+## Typography Tokens
+### Font Family
+| Token | Tailwind | Default |
+|-------|----------|---------|
+| `--font-body` | `font-sans` | Geist Sans (bundled) |
+| `--font-headline` | `font-headline` | Geist Sans |
+| `--font-quote` | `font-quote` | Redaction (bundled) |
+| `--font-quote-alt` | `font-quote-alt` | Redaction 35 |
+| `--font-code` | `font-code` | Geist Mono (bundled) |
+### Font Size (Tailwind v3 classes)
+Use `text-xs` through `text-9xl` — these are native Tailwind classes wired to SortUI tokens. **Do NOT use `text-sui-*` font-size classes.**
+| Class | Size | Usage |
+|-------|------|-------|
+| `text-xs` | 12px | Small labels, captions |
+| `text-sm` | 14px | Body text (small) |
+| `text-base` | 16px | Body text (default) — also `text-md` |
+| `text-lg` | 18px | Large body text |
+| `text-xl` | 20px | Small headings |
+| `text-2xl` | 24px | Headings (H3) |
+| `text-3xl` | 30px | Headings (H2) |
+| `text-4xl` | 36px | Headings (H1) |
+| `text-5xl` – `text-9xl` | 48–128px | Display / hero text |
+### Font Weight
+`font-light` (300), `font-normal` (400), `font-medium` (500), `font-semibold` (600), `font-bold` (700), `font-extrabold` (800), `font-black` (900).
+---
+## Shadow Tokens (NO `sui-` prefix)
+Use ONLY these Figma-aligned shadow classes. **Never** use `shadow-sm`, `shadow-md`, `shadow-lg`, arbitrary `shadow-[…]`, or `shadow-sui-*`.
+| Tailwind class | CSS var | Usage |
+|----------------|---------|-------|
+| `shadow-default` | `--shadow-default` | Default element shadow |
+| `shadow-card` | `--shadow-card` | Card shadow |
+| `shadow-card-base` | `--shadow-card-base` | Base card shadow |
+| `shadow-focus` | `--shadow-focus` | Focus ring |
+| `shadow-destructive-focus` | `--shadow-destructive-focus` | Destructive focus ring |
+| `shadow-misc-focus` | `--shadow-misc-focus` | Misc focus |
+| `shadow-input-focus` | `--shadow-input-focus` | Input focus |
+| `shadow-modal-sm` | `--shadow-modal-sm` | Small modal |
+| `shadow-modal-md` | `--shadow-modal-md` | Medium modal |
+| `shadow-modal-lg` | `--shadow-modal-lg` | Large modal |
+| `shadow-switch-handle` | `--shadow-switch-handle` | Switch handle |
+| `shadow-checkbox` / `shadow-checkbox-active` | | Checkbox |
+| `shadow-inset-bottom` / `-soft` / `-strong` | | Inset bottom |
+| `shadow-tab-active` | `--shadow-tab-active` | Active tab |
+| `shadow-button-default` / `-press` / `-secondary` / `-secondary-press` | | Button shadows |
+```tsx
+<div className="shadow-card" />
+<div className="shadow-default" />
+<button className="shadow-button-default active:shadow-button-press" />
+```
+---
+## Border & Radius Tokens
+### Border Width (NO `sui-` prefix)
+| Class | Width |
+|-------|-------|
+| `border-sm` | 0.5px |
+| `border` | 1px (default) |
+| `border-md` | 1.5px |
+| `border-lg` | 2px |
+| `border-xl` | 3px |
+| `border-2xl` | 4px |
+### Border Radius (NO `sui-` prefix)
+| Class | Radius |
+|-------|--------|
+| `rounded-none` | 0px |
+| `rounded-2xs` | 2px |
+| `rounded-xs` | 4px |
+| `rounded-sm` | 6px |
+| `rounded-md` | 8px |
+| `rounded-lg` | 12px |
+| `rounded-xl` | 16px |
+| `rounded-2xl` | 24px |
+| `rounded-3xl` | 28px |
+| `rounded-full` | 9999px (pill) |
+| `rounded-card-none` / `-xs` / `-sm` / `-md` / `-lg` | Card-specific |
+```tsx
+<div className="rounded-md" />      {/* 8px */}
+<div className="rounded-lg" />      {/* 12px */}
+<div className="rounded-full" />    {/* pill */}
+<div className="rounded-card-md" /> {/* card-aligned */}
+```
+---
+## Spacing Tokens (WITH `sui-` prefix)
+Use spacing tokens from `--spacing-1` to `--spacing-384`, exposed as `p-sui-16`, `gap-sui-12`, etc.
+| Class | Size | Common usage |
+|-------|------|--------------|
+| `gap-sui-none` | 0 | No spacing |
+| `gap-sui-4` | 4px | Tight groups |
+| `gap-sui-8` | 8px | Small |
+| `gap-sui-12` | 12px | Inline items |
+| `gap-sui-16` | 16px | Form fields |
+| `gap-sui-20` | 20px | Medium+ |
+| `gap-sui-24` | 24px | Card internal |
+| `gap-sui-32` | 32px | Section break |
+| `gap-sui-48` | 48px | Major section |
+| `gap-sui-64` | 64px | Page section |
+Works across all spacing utilities: `p-`, `m-`, `gap-`, `space-x-`, `space-y-`, etc.
+```tsx
+<div className="gap-sui-16 p-sui-24" />
+<div className="space-y-sui-16" />
+<div className="mx-sui-32 my-sui-24" />
+```
+---
+## DO / DON'T
+**DO:**
+```tsx
+// Semantic color tokens
+<div className="bg-sui-bg-subtle text-sui-text-default border border-sui-border-default" />
+// Correct radius (NO sui- prefix)
+<div className="rounded-md" />
+<div className="rounded-lg" />
+// Correct shadow (NO sui- prefix)
+<div className="shadow-card" />
+<div className="shadow-default" />
+// Correct spacing (WITH sui- prefix)
+<div className="p-sui-24 gap-sui-16" />
+// CSS variable for dynamic values
+<div style={{ color: "var(--text-subtle)" }} />
+```
+**DON'T:**
+```tsx
+// ❌ sui- prefix on radius/shadow
+<div className="rounded-sui-md shadow-sui-default" />
+// ❌ Generic Tailwind shadow primitives
+<div className="shadow-md shadow-lg" />
+// ❌ Hardcoded hex/arbitrary values
+<div className="bg-[#fafafa] text-[#111115] gap-[16px]" />
+// ❌ Missing sui- on colors/spacing
+<div className="bg-bg-default text-text-default gap-16" />
+```
+---
+## Token Usage Examples
+**Card:**
+```tsx
+<div className="bg-sui-bg-card border border-sui-border-default rounded-card-md shadow-card p-sui-24">
+  <h3 className="text-sui-text-default font-semibold">Card title</h3>
+  <p className="text-sui-text-subtle">Card body</p>
+</div>
+```
+**Button (primary):**
+```css
+.custom-button {
+  background: var(--bg-state-primary);
+  color: var(--text-inverted-default);
+  border-radius: var(--radius-md);
+  padding: var(--spacing-12) var(--spacing-24);
+  box-shadow: var(--shadow-button-default);
+}
+.custom-button:hover { background: var(--bg-state-primary-hover); }
+.custom-button:active { box-shadow: var(--shadow-button-press); }
+```
+**Input:**
+```css
+.custom-input {
+  background: var(--bg-default);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  color: var(--text-default);
+  padding: var(--spacing-8) var(--spacing-12);
+}
+.custom-input:focus {
+  border-color: var(--border-informative);
+  box-shadow: var(--shadow-input-focus);
+}
+```
+---
+## Chart Color Tokens
+For data visualization (Recharts integration):
+| Token | Default |
+|-------|---------|
+| `--chart-1` | blue |
+| `--chart-2` | green |
+| `--chart-3` | orange |
+| `--chart-4` | red |
+| `--chart-5` | purple |
+**Usage in charts (note `isAnimationActive={false}` — required for React 19):**
+```tsx
+<Line dataKey="revenue" stroke="var(--chart-1)" isAnimationActive={false} />
+<Bar  dataKey="sales"   fill="var(--chart-2)"   isAnimationActive={false} />
+```
+---
+## Summary
+- **Use semantic tokens** over raw values
+- **Tokens are CSS custom properties** (`var(--token-name)`)
+- **Tailwind v3** utility classes — never emit Tailwind v4 syntax
+- **Selective `sui-` prefix** — colors + spacing yes; radius + shadow + border-width + font-size no
+- **Theming** via class on root element (`light`, `dark`, `theme-2`, `theme-2-dark`)
+- **All tokens** automatically adapt to theme changes

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maxsteinwender/sort-ui",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A coded design system based on Sort UI Kit — Figma components as production-ready Next.js/Tailwind components",
   "author": "Max Steinwender",
   "license": "UNLICENSED",
@@ -26,7 +26,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "guidelines"
   ],
   "sideEffects": [
     "*.css"